Call details API
Read your calls, their outcome, cost and recording from your own systems.
Read the details of your Vonyx calls from your own systems: the same details the console's call logs show. Look up one call by its id, or list your calls, newest first, one page at a time.
1. Basics
Requests
- Base URL:
https://api.vocalstack.site. Usehttps://. - Both endpoints are read with
GET. Parameters go in the URL; there is no request body. - Write the list URL without a slash at the end:
/v1/calls?…. With the slash,/v1/calls/?…is read as a lookup of one call and fails with400. - A
POSTto/v1/callsis not a read: it places a call.
This API does not use the token that listing numbers and placing calls need. Every request names your account with the client_id parameter: your client ID, a UUID such as 5b9d2a7e-1c4f-4e8a-9d3b-6f0e2c8a1b47. It is the Account ID in the console's Settings.
A wrong client ID is not an error
The API checks only that your client ID is a UUID, not that it is the right one. With a mistyped client ID, lists come back empty and every call is 404. If you see no calls where you expect some, check your client ID first.
Responses
Every response is a JSON object with the same envelope:
| Field | Description |
|---|---|
status | The HTTP status code, repeated in the body. |
message | A short summary: "ok" on success. |
data | Only on success: the call, or the page of calls. |
error | On most errors: what was wrong, for example "limit must be 1 to 200". |
- Times are UTC, in ISO 8601 with milliseconds:
2026-10-23T10:15:02.120Z. The call status webhook uses India time; this API always uses UTC. - Phone numbers are digits only, without
+. The exception is thefromof an inbound call that has no caller number: it isanonymousor empty (""), see section 7. - Durations are in seconds, with up to 3 decimals.
2. Which calls are listed
Your calls are listed whether they were answered or not: the calls you place, through your SIP trunk or with POST /v1/calls, and the calls to your numbers, whether they go to your SIP system or to your WebSocket agent. A call is listed once it has ended, usually within a few seconds of the hang-up. Calls in progress are not listed.
Calls that were refused or turned away:
| The call | Listed? |
|---|---|
| Through your SIP trunk, refused when Vonyx checked your account, for example because all your channels were in use | Yes, with status rejected; reason says why. |
| Through your SIP trunk, refused before that check: its From is not your Vonyx number, the number called is not a valid Indian number, or your SIP login has no number yet | No. Your SIP system gets the refusal at once: SIP 484 when the number called is not valid, 403 otherwise. |
Placed with POST /v1/calls and refused, for example because all your channels were in use | No. The refusal is in that request's response. |
To your WebSocket agent, declined because your answer webhook could not be reached, did not reply within 2 seconds, or did not reply with a usable websocket_url | No, and it is not charged. Looking up its call_id stays 404. |
| To your WebSocket agent, and the caller hung up while Vonyx was still waiting for your answer webhook | Yes, with status cancelled. |
| To your SIP system, turned away because inbound calls are not switched on for your SIP trunk (or have no address to go to), or the trunk is disabled | Yes, with status cancelled, an empty from and result null. |
3. Get one call
| Parameter | In | Description |
|---|---|---|
call_id | path | The call's id (a UUID): the call_id that POST /v1/calls returned, the CallUUID in the call's status webhook, the call_id your answer webhook received for an inbound call, or a call_id from the list. |
client_id | query | Your client ID. |
Looking up one call has no time window: any of your calls can be fetched by its id, however old.
For calls through your SIP trunk or to your SIP system, Vonyx does not send its call id to your SIP system, so find those calls with the list (section 11).
Response 200, here a call placed with POST /v1/calls:
Every field is described in section 7.
Response 404: your account has no call with this id.
A call that ended a moment ago can be 404 for a few seconds, until its record is written: retry shortly. A call that is not listed (section 2) stays 404, and so does a call of another account.
4. List calls
| Parameter | Default | Description |
|---|---|---|
client_id | required | Your client ID. |
limit | 50 | Calls per page, 1 to 200. |
cursor | first page | The next_cursor of the previous page (section 5). |
from | to minus 7 days | Start of the time window, included (section 6). |
to | now | End of the time window, not included. |
direction | both | inbound or outbound. |
status | any | completed, no-answer, busy, cancelled, fail or rejected (section 7). |
number | any | Only calls from or to this number (section 6). |
Filters combine: a call is listed only if it matches all of them.
Parameters not in this table are ignored, and an optional parameter sent empty (for example status=) counts as not sent. So a misspelled name, such as form instead of from, is not an error: the default applies instead. If a parameter is sent twice, the first value is used.
Response 200:
| Field | Description |
|---|---|
calls | Up to limit calls, newest first (section 7). An empty list, [], when no call matches. |
has_more | true when more calls match: there is at least one more page. |
next_cursor | What to send as cursor for the next page. null on the last page. |
Calls come newest first, by when each call's record was created, which is right after the call ended. Calls recorded at the same moment always come in the same order.
5. Paging
A list returns at most limit calls. To get every call that matches, follow the cursor:
- Ask for the first page, without
cursor. - If
has_moreistrue, ask again with the same parameters, pluscursorset to that page'snext_cursor. - Repeat until
has_moreisfalse. On that last page,next_cursorisnull.
Good to know:
- Send the same
fromandtoon every page. If you leave them out, each request uses the 7 days before that request, so the window moves while you page. - The cursor marks the last call of the page you got; the next page starts right after it. Pass it back unchanged and don't build one yourself. It is safe in a URL as it is, and it does not expire.
- Pages don't shift: calls that end while you are paging never make you see a call twice or miss one. They appear on the first page of your next walk.
- There is no total count and there are no page numbers.
- A deep page is as fast as the first one.
- Ask for the pages one after the other, not in parallel (section 9).
6. Time window and filters
Time window: from and to
Calls are filtered by when their record was created, which is right after the call ended. from is included, to is not.
- Format: an ISO 8601 (RFC 3339) time with a time zone, such as
2026-10-16T00:00:00Z(UTC) or2026-10-16T05:30:00+05:30. In a URL, write the+as%2B(2026-10-16T05:30:00%2B05:30), or use UTC withZ. Fractional seconds are allowed. A time without a time zone, or a date alone, is a400. - Defaults:
tois now, andfromis 7 days beforeto. frommust be beforeto, at most 31 days apart. If you send onlyfrom,tois the time of each request, sofrommust be within the last 31 days, also on the later pages while you page.
The 31 days limit the width of one window, not how far back it can go: with both from and to, any earlier period works, for example from=2026-01-01T00:00:00Z&to=2026-02-01T00:00:00Z. For a period longer than 31 days, read it window by window.
| To get | Send |
|---|---|
| The last 7 days | neither from nor to |
| Calls recorded on 23 October 2026, India time | from=2026-10-22T18:30:00Z&to=2026-10-23T18:30:00Z |
| October 2026, UTC (31 days, the maximum) | from=2026-10-01T00:00:00Z&to=2026-11-01T00:00:00Z |
| The 7 days up to a time you choose: here 3 to 10 October 2026, 00:00 UTC | to=2026-10-10T00:00:00Z (only to: from becomes 7 days earlier) |
| Everything from a time you choose up to now: here from 20 October 2026, 00:00 UTC | from=2026-10-20T00:00:00Z (only from: to becomes now) |
A call is in the window that holds the moment its record was created, usually a few seconds after it ended. So a call that ended just before midnight can be in the next day's window. To report by the day a call started, read a slightly wider window and keep the calls whose started_at falls on that day.
direction and status
direction=inbound or direction=outbound. status takes one of the values in section 7, for example status=no-answer.
number
Only calls whose from or to ends with the same last 10 digits as this number.
- Send digits, 8 to 20 of them. A leading
+or00is ignored. Spaces, dashes or brackets are a400. - The number is matched on its last 10 digits, so
919876543210,+919876543210,09876543210and9876543210find the same calls, however a call record holds the number. A number shorter than 10 digits finds calls whose number ends with it. A number from another country that ends in the same 10 digits matches too. - A number search reads all your calls in the window, so on a busy account a shorter window answers faster. A request that Vonyx cannot answer within 5 seconds ends with
503: if a number search keeps getting503, use a shorter window.
7. Call fields
| Field | Type | Description |
|---|---|---|
call_id | string | The call's id (a UUID). |
direction | string | outbound: a call you placed. inbound: a call to one of your numbers. |
from | string | Outbound: your number the call was made from. Inbound: the caller's number; anonymous or empty ("") when there is no caller number, for example when the caller withheld it. |
to | string | Outbound: the number you called, as its 10 digits (9876543210); some older records hold it with more digits in front. Inbound: your number that was called. |
status | string | How the call ended (see Status values). |
result | string or null | The outcome of dialing (see Result values). |
started_at | string | When the call started. For a call through your SIP trunk, when it reached Vonyx. For a call placed with POST /v1/calls, when Vonyx started dialing it, after any wait for a free line; that wait happens while your request is still open. For a call to your number, when it reached your number. |
answered_at | string or null | When the call was answered; null if it wasn't. |
ended_at | string | When the call ended. |
ringing_seconds | number or null | For a call to your SIP system: seconds from Vonyx calling your SIP system until it signalled ringing. For a call through your SIP trunk, Vonyx signals ringing itself as soon as it starts placing the call, so the value is always a fraction of a second and says nothing about the phone. null when no ringing was signalled, and always for calls through a WebSocket agent. To see how long an answered call took to be answered, use answered_at minus started_at; for a call through your SIP trunk, that includes any wait before the call was placed. |
duration_seconds | number | From started_at to ended_at, including ringing. For a call through your SIP trunk, this also includes any wait before the call was placed. |
billed_seconds | number | How long the call was connected, from answered_at to ended_at. 0 if it wasn't answered. |
cost | number | What the call cost, deducted from your balance: its connected time in whole seconds (fractions of a second are dropped, so 63.9 seconds counts as 63), rounded up to your billing pulse, at your per-minute rate, to 2 decimals. 0 for a call not answered, or answered for less than a second. |
hung_up_by | string | Who ended the call (see Who hung up). |
hangup_cause | integer or null | The telephony cause code (Q.850, see Hangup cause codes); null for calls through a WebSocket agent. |
reason | string or null | Why a call failed, was refused, or was cancelled before it was placed (see Reasons). null for most calls. |
recording_url | string or null | A link to the call's recording, a WAV file, for answered calls; null otherwise. The recording is stored after the call ends, so the link can fail for a short while after the call is listed, and in rare cases no recording is stored. Anyone who has the link can download the recording: keep it as private as your client ID. |
sip_username | string | The SIP username the call used; websocket for calls through a WebSocket agent. |
Status values
status | Meaning |
|---|---|
completed | The call was answered. |
no-answer | It rang, but no one answered in time. |
busy | The called side was busy. For calls through a WebSocket agent, busy also covers a call that was declined, or that the network reported as unavailable or congested. |
cancelled | It ended before it was answered: the calling side hung up first, also while the call was waiting to be placed. An inbound call to your SIP system that Vonyx turned away (section 2) is also cancelled. |
fail | It could not be connected, for example because the number or the network could not be reached. For calls through your SIP trunk or to your SIP system, a declined call is also fail, with result chanunavail and hangup_cause 21. reason says how it failed. |
rejected | Vonyx refused it before placing it, for example because of a limit on your account. reason says why. |
Result values
The outcome of dialing, as the network reported it:
result | Meaning |
|---|---|
answered | Answered. |
no-answer | Not answered in time. |
busy | Busy (see status busy). |
cancelled | The calling side hung up before an answer. |
| another value | Another outcome, in lower case, for example chanunavail, congestion or invalid-number. For calls through your SIP trunk or to your SIP system, chanunavail covers every outcome other than busy, congestion and no answer: a declined call, a number that does not exist, a network timeout and others, which hangup_cause tells apart. congestion means the network or Vonyx had no free capacity at that moment. |
null | Nothing was dialed, for example for a rejected call. |
Who hung up
hung_up_by | Who ended the call |
|---|---|
customer | Your side: your SIP system or your WebSocket agent. |
carrier | The other side: the person on the phone hung up, or their network ended the call. |
system | Vonyx, for example when your WebSocket agent could not be reached. |
gate | Vonyx refused the call before placing it (status rejected). |
For a call that was not answered, hung_up_by does not tell you which side gave up: use status, result and hangup_cause. A call through your SIP trunk or to your SIP system shows system when the called side was busy, declined it, did not answer or could not be reached; if the calling side hung up first, it shows that side. A call through a WebSocket agent that was not answered shows carrier, also when no one answered within the ringing time.
Reasons
reason | With status | Meaning |
|---|---|---|
client_channels | rejected | All your channels (calls at the same time) were in use. |
client_cps | rejected | Calls were started faster than your calls-per-second limit. |
no_balance | rejected | Your balance was below zero when Vonyx last checked it. Balances are checked every few minutes, so after a top-up, calls can still be refused for a few minutes. |
gate_down | rejected | Vonyx could not check your limits at that moment and refused the call. Try again. |
no_config, no_pool | rejected | Your account or number is not fully set up for this call. Contact support. |
cancelled_while_queued | cancelled | The call was waiting for a free line on the network your number uses, and your side hung up before it was placed. Only Vonyx's capacity on that network makes a call wait: a call over your own limits is rejected at once. A waiting call already counts toward your channels, and your SIP system gets no ringing while it waits. |
| the dial outcome | fail | The same as result, for example chanunavail. |
Other values can appear. Treat a reason you don't know as information only.
Hangup cause codes
hangup_cause is the standard Q.850 cause. The common ones:
| Code | Meaning |
|---|---|
1 | Unallocated (unassigned) number |
16 | Normal call clearing |
17 | User busy |
18 | No user responding |
19 | No answer |
21 | Call rejected |
27 | Destination out of order |
28 | Invalid number format |
31 | Normal, unspecified |
34 | No circuit or channel available |
38 | Network out of order |
41 | Temporary failure |
127 | Interworking, unspecified |
Compared with the call status webhook
If you also receive the call status webhook (calls through a WebSocket agent), its fields compare like this:
| Call status webhook | This API |
|---|---|
CallUUID | call_id |
StartTime, EndTime: India time, YYYY-MM-DD HH:MM:SS | started_at, ended_at: UTC, ISO 8601 |
Duration: the connected time, in whole seconds | billed_seconds (with decimals), not duration_seconds |
CallStatus | Usually the same as status. invalid-number there is status fail with result invalid-number here. |
HangupSource user | hung_up_by carrier, also for calls that were never answered |
HangupSource server | customer |
HangupSource Websocket, ws_connect_failed or forwarded | system |
Any other HangupSource, such as the hangupType your agent sent | customer |
8. Errors
Errors use the same envelope:
| HTTP | message | Meaning | What to do |
|---|---|---|---|
400 | Invalid request | A parameter is missing or wrong; error says which. | Fix the request. Sent again unchanged, it fails the same way. |
404 | Call not found | Get one call: your account has no call with this id, or not yet. | Check the id and your client ID. For a call that ended a moment ago, retry after a few seconds. A call that is not listed (section 2) stays 404. |
405 | Method not allowed | A method other than GET. On /v1/calls, a method other than GET or POST: error then says use POST. | Use GET. |
429 | Too many requests | A limit in section 9 was reached. | Wait at least a second, then retry. |
503 | Could not read the call, try again / Could not read calls, try again | A temporary problem on Vonyx's side, or a request that could not be answered within 5 seconds. | Retry after a few seconds. If a number search keeps getting 503, use a shorter window. |
Treat any other 5xx (its body may not be JSON), or no response within about 30 seconds, like a 503.
The error texts of a 400 are meant for people: in code, act on the HTTP status, since the wording can change. What they cover:
| Problem | error, for example |
|---|---|
client_id missing or not a UUID | client_id must be your client id (a uuid) |
| The call id in the path is not a UUID | the call id in the path must be a uuid |
limit not a whole number from 1 to 200 | limit must be 1 to 200 |
from or to not a time with a time zone | from must be a time like 2026-10-16T00:00:00Z |
from not before to | from must be before to |
from and to more than 31 days apart | from and to may be at most 31 days apart |
direction not inbound or outbound | direction must be inbound or outbound |
status not one of the values | status must be one of completed, no-answer, busy, cancelled, fail, rejected |
number not 8 to 20 digits | number must be digits, … |
cursor changed, or not from this API | cursor must be a next_cursor this API returned |
9. Limits
| Limit | Value | Over it |
|---|---|---|
| Calls per page | 200 (default 50) | 400 |
| Time window per request | 31 days (default 7) | 400 |
| List requests running at the same time | 2 per client ID | 429 |
| Requests per second | 5 per IP address, with short bursts of up to 10 | 429 |
| Time to answer one request | 5 seconds | 503 |
- Looking up one call does not count toward the 2 list requests at the same time.
- The per-second limit counts both endpoints together, for all requests from one IP address.
- Placing calls with
POST /v1/callsis not affected by these limits. - After a
429, wait at least a second before retrying. The examples in section 10 do this.
10. Code examples
11. Common tasks
Get a call's details after it ends
For a call through a WebSocket agent, take its id (the call_id from POST /v1/calls, or the CallUUID of its status webhook) and call GET /v1/calls/{call_id} once the call has ended. A 404 in the first seconds after the hang-up means the record is not written yet: try again a few times, a few seconds apart. If it is still 404 after a minute, the call is most likely one that is not listed (section 2).
For a call through your SIP trunk or to your SIP system, your SIP system is not given Vonyx's call id. Find the call with the list instead: send number (the number called or, for an inbound call, the caller's number or your own number) and a time window that covers the call, then pick the call by started_at.
Keep your own copy of your calls up to date
Every few minutes:
- List with
from= thetoof your previous run minus 2 minutes, andto= now. On the first run, start from the earliest time you need, reading it window by window (section 6). - Save each call by its
call_id, replacing a call you already have. The 2-minute overlap then only brings calls you can recognise. - Once you have read every page, keep this run's
tofor the next run. If a run fails, run it again with the samefrom.
Calls are filtered by when their record was created, so a call that is recorded late still falls into a later window, and the overlap covers records written while you read. This relies on your server's clock being right: keep it synchronised, for example with NTP.
Export a longer period
Read it in windows of up to 31 days, for example month by month, and page through each window.
12. Questions
A call I just made doesn't show up. Calls are listed once they have ended, usually within a few seconds of the hang-up. Some refused calls are never listed (section 2).
I get no calls at all. Check your client ID: a wrong one is not an error, it just finds no calls (section 1).
I only see the last 7 days. That is the default window. Send from and to to read another period (section 6).
What time zone are the times in? UTC. India time is UTC+05:30.
Why is to 10 digits on my outbound calls? Numbers you call are recorded as their 10 digits, without the 91. To search for a number, any of its forms works (section 6).
I get 429. Run at most 2 list requests at the same time, and stay under 5 requests a second (section 9).