Skip to main content
List calls
Cursor pagination. Pass the response’s next_cursor back as ?cursor= for the next page; has_more is false on the last page. Cursors are opaque - don’t parse them. An invalid cursor returns 400 invalid_cursor.
Voice conversations only. This endpoint covers phone legs and browser audio - a voice call from your embedded widget, and a voice test run from the Vocily dashboard. Text conversations are a separate resource at /v1/chats, because they are priced per assistant reply and carry no numbers, duration or recording.
transcript is null in list items unless you pass include=transcript.

Slicing the list

Two fields describe a call’s provenance, and they answer different questions. direction is which way it went: inbound, outbound, or web for a call that happened in a browser rather than on a phone. A web call carries no numbers - from_number and to_number are null. origin is who started it:
?direction= takes the same three values the field publishes - inbound, outbound or web. Anything else, including a value you may have seen in a stored record, returns 400 invalid_direction.
?origin= takes a comma-separated list, which is the way to separate real traffic from your own testing:
origin is null on a call whose source could not be attributed. Those rows are excluded when ?origin= is set, since the filter names specific sources - so a filtered count can be lower than an unfiltered one. Read null as unknown rather than as a channel.

Authorizations

Authorization
string
header
required

Your API key as a Bearer token, e.g. Authorization: Bearer vk_….

Query Parameters

agent_id
string | null

Filter by agent id

status
string | null

Filter: started | in_progress | completed | voicemail | no_answer | busy | declined | failed | transferring | transfer_answered | transfer_completed | transfer_failed

direction
string | null

Filter: inbound, outbound, or web for calls that happened in a browser (widget calls and dashboard tests). Omit for all three.

origin
string | null

Filter by who started it — comma-list of: widget | dashboard | api | batch | inbound | demo. Use it to exclude your own dashboard test calls, e.g. ?origin=api,inbound. Rows with an unknown origin are excluded when this is set.

date_from
string<date-time> | null

started_at >= this datetime

date_to
string<date-time> | null

started_at <= this datetime

cursor
string | null

Opaque cursor from a previous response's next_cursor; omit for the first page

include
string | null

Comma-list of heavy fields to include. Currently: transcript

limit
integer
default:20

Maximum records to return in one page.

Required range: 1 <= x <= 100

Response

Successful Response

A page of calls. Pass next_cursor back as ?cursor= to fetch the next one; has_more is false on the last page. Cursors rather than an offset, so a call placed while you are paging cannot shift rows onto a page you have already read.

data
PublicCallRead · object[]
required

The page of calls.

has_more
boolean
required

Whether another page exists.

next_cursor
string | null
required

Pass as cursor to fetch the next page. null on the last page.