Skip to navigation

List calls

Returns the calls of the organization in a period, newest first by default, one page at a time. Each item has times, duration, direction, status, the two phone numbers, the agent and the outcome of the report card. The summary, the collected data and the transcript are never in the list: read them on the single call. There is no filter by caller number on purpose (a phone number must not travel in a URL): to find the data of a person use POST /caller-requests/search. Required scope: calls:read. With a test key (vx_test_) it behaves exactly as with a live key and consumes nothing.

Authentication

AuthorizationBearer
API key created by an Owner or Admin of the organization. Never in the query string.

Headers

VoxAI-VersionenumOptional

API version for this request; defaults to the version the key is pinned to.

Allowed values:

Query parameters

periodenumOptional

The period to read, in the timezone. Default 7d. today: from midnight to now. 7d, 30d: the last 7 or 30 days, today included. last_month: the previous calendar month. 6m, 12m: the last 6 or 12 months. custom: from from to to, at most 13 months.

fromstringOptionalformat: "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"

First day of a custom period, YYYY-MM-DD, in the timezone. Only with period=custom.

tostringOptionalformat: "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"

Last day of a custom period, YYYY-MM-DD, included. Only with period=custom.

timezonestringOptionalformat: "^[A-Za-z0-9_+/-]+$"1-64 characters

IANA time zone the period is computed in, for example Europe/Rome (default). It decides where days start and end.

statusstringOptionalformat: "^(completed|interrupted|failed|in_progress|forwarded|missed_lines_busy|missed_quota|missed_suspended|missed_platform|missed_agent_suspended)(,(completed|interrupted|failed|in_progress|forwarded|missed_lines_busy|missed_quota|missed_suspended|missed_platform|missed_agent_suspended)){0,9}$"

Only calls with one of these statuses, comma-separated: completed, interrupted, failed, in_progress, forwarded, missed_lines_busy, missed_quota, missed_suspended, missed_platform, missed_agent_suspended. completed also matches calls transferred to a person (transferred is not a filter value). The meaning of each value is in status of the response.

missedbooleanOptional

true: only calls rejected before an agent answered (missed_*). false: only answered calls. Omitted: both.

agent_idstringOptionalformat: "^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"
Only the calls handled by this agent.
directionenumOptional

Only one channel. inbound: phone calls received. outbound: phone calls made by an agent. web: conversations in the web widget.

Allowed values:
linestringOptionalformat: "^[+0-9 ().-]+$"6-24 characters

Only the calls on this phone line of the organization (not the caller number), in international format, for example +390212345678. The lines are listed by GET /lines.

report_cardenumOptional

Only calls with this report card outcome: positive, needs_review, negative, or not_evaluated (no report card, or not computed yet).

Allowed values:
has_handoffbooleanOptional

true: only calls that passed between agents of a team. false or omitted: every call.

orderenumOptionalDefaults to desc

Order by start time: desc newest first (default), asc oldest first. The cursor is tied to the order: do not change it between pages.

Allowed values:
limitintegerOptional1-100Defaults to 20
Maximum number of items in the page, from 1 to 100. Default 20.
cursorstringOptional1-400 characters

Opaque cursor from next_cursor of the previous page, to read the next one. Pass it back unchanged, with the same filters; omit it for the first page.

Response

Successful response.
datalist of objects
The items of this page, in the requested order.
has_moreboolean

true if there are more items after this page.

next_cursorstring or null

Pass it as cursor to read the next page; null on the last page.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error