# 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](/docs/console/call-logs) show. Look up one call by its id, or list your calls, newest first, one page at a time.

```http
GET https://api.vocalstack.site/v1/calls/{call_id}?client_id=YOUR_CLIENT_ID   # one call
GET https://api.vocalstack.site/v1/calls?client_id=YOUR_CLIENT_ID             # your calls, page by page
```

## 1. Basics

### Requests

- Base URL: `https://api.vocalstack.site`. Use `https://`.
- 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 with `400`.
- A `POST` to `/v1/calls` is not a read: it [places a call](/docs/call-api).

This API does not use the [token](/docs/call-api/authentication) 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**.

<Callout type="warn" title="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.
</Callout>

### Responses

Every response is a JSON object with the same envelope:

```json
{ "status": 200, "message": "ok", "data": {} }
```

| 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 the `from` of an inbound call that has no caller number: it is `anonymous` or 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

```http
GET /v1/calls/{call_id}?client_id=YOUR_CLIENT_ID
```

| 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).

```bash
curl 'https://api.vocalstack.site/v1/calls/3f2b6c1e-8a4d-4c2e-9b1f-5d7e8a9c0b12?client_id=YOUR_CLIENT_ID'
```

Response `200`, here a call placed with `POST /v1/calls`:

```json
{
  "status": 200,
  "message": "ok",
  "data": {
    "call_id": "3f2b6c1e-8a4d-4c2e-9b1f-5d7e8a9c0b12",
    "direction": "outbound",
    "from": "918012345678",
    "to": "9876543210",
    "status": "completed",
    "result": "answered",
    "started_at": "2026-10-23T10:15:02.120Z",
    "answered_at": "2026-10-23T10:15:09.480Z",
    "ended_at": "2026-10-23T10:16:12.900Z",
    "ringing_seconds": null,
    "duration_seconds": 70.78,
    "billed_seconds": 63.42,
    "cost": 2,
    "hung_up_by": "carrier",
    "hangup_cause": null,
    "reason": null,
    "recording_url": "https://…/3f2b6c1e-8a4d-4c2e-9b1f-5d7e8a9c0b12.wav",
    "sip_username": "websocket"
  }
}
```

Every field is described in section 7.

Response `404`: your account has no call with this id.

```json
{ "status": 404, "message": "Call not found", "error": "no call 3f2b6c1e-8a4d-4c2e-9b1f-5d7e8a9c0b12 for this client" }
```

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

```http
GET /v1/calls?client_id=YOUR_CLIENT_ID
```

| 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.

```bash
curl 'https://api.vocalstack.site/v1/calls?client_id=YOUR_CLIENT_ID&limit=2'
```

Response `200`:

```json
{
  "status": 200,
  "message": "ok",
  "data": {
    "calls": [
      {
        "call_id": "9a4e7c2b-6d1f-4b3a-8e5c-0f2d4a6b8c1e",
        "direction": "outbound",
        "from": "918012345678",
        "to": "9123456789",
        "status": "no-answer",
        "result": "no-answer",
        "started_at": "2026-10-23T10:19:30.004Z",
        "answered_at": null,
        "ended_at": "2026-10-23T10:20:15.521Z",
        "ringing_seconds": 0.012,
        "duration_seconds": 45.517,
        "billed_seconds": 0,
        "cost": 0,
        "hung_up_by": "system",
        "hangup_cause": 19,
        "reason": null,
        "recording_url": null,
        "sip_username": "vs_x7k2m9qp"
      },
      {
        "call_id": "3f2b6c1e-8a4d-4c2e-9b1f-5d7e8a9c0b12",
        "direction": "outbound",
        "from": "918012345678",
        "to": "9876543210",
        "status": "completed",
        "result": "answered",
        "started_at": "2026-10-23T10:15:02.120Z",
        "answered_at": "2026-10-23T10:15:09.480Z",
        "ended_at": "2026-10-23T10:16:12.900Z",
        "ringing_seconds": null,
        "duration_seconds": 70.78,
        "billed_seconds": 63.42,
        "cost": 2,
        "hung_up_by": "carrier",
        "hangup_cause": null,
        "reason": null,
        "recording_url": "https://…/3f2b6c1e-8a4d-4c2e-9b1f-5d7e8a9c0b12.wav",
        "sip_username": "websocket"
      }
    ],
    "has_more": true,
    "next_cursor": "MjAyNi0xMC0yM1QxMDoxNjoxMy4wNTE4MjYrMDA6MDB8M2YyYjZjMWUtOGE0ZC00YzJlLTliMWYtNWQ3ZThhOWMwYjEy"
  }
}
```

| 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:

1. Ask for the first page, without `cursor`.
2. If `has_more` is `true`, ask again with the same parameters, plus `cursor` set to that page's `next_cursor`.
3. Repeat until `has_more` is `false`. On that last page, `next_cursor` is `null`.

```bash
# page 1
curl 'https://api.vocalstack.site/v1/calls?client_id=YOUR_CLIENT_ID&from=2026-10-01T00:00:00Z&to=2026-10-08T00:00:00Z&limit=200'
# page 2: the same request, plus the next_cursor of page 1
curl 'https://api.vocalstack.site/v1/calls?client_id=YOUR_CLIENT_ID&from=2026-10-01T00:00:00Z&to=2026-10-08T00:00:00Z&limit=200&cursor=NEXT_CURSOR_OF_PAGE_1'
```

Good to know:

- Send the same `from` and `to` on 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) or `2026-10-16T05:30:00+05:30`. In a URL, write the `+` as `%2B` (`2026-10-16T05:30:00%2B05:30`), or use UTC with `Z`. Fractional seconds are allowed. A time without a time zone, or a date alone, is a `400`.
- **Defaults:** `to` is now, and `from` is 7 days before `to`.
- `from` must be before `to`, at most **31 days** apart. If you send only `from`, `to` is the time of each request, so `from` must 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 `+` or `00` is ignored. Spaces, dashes or brackets are a `400`.
- The number is matched on its last 10 digits, so `919876543210`, `+919876543210`, `09876543210` and `9876543210` find 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 getting `503`, 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](/docs/call-api/status-webhooks) (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:

```json
{ "status": 400, "message": "Invalid request", "error": "limit must be 1 to 200" }
```

| 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/calls` is 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

<Tabs items={['curl', 'Python', 'JavaScript']}>
<Tab value="curl">

```bash
# Your calls of the last 7 days, newest first, 50 per page
curl 'https://api.vocalstack.site/v1/calls?client_id=YOUR_CLIENT_ID'

# Outbound calls that rang but were not answered (status no-answer),
# recorded on 23 October 2026 (India time), 200 per page
curl 'https://api.vocalstack.site/v1/calls?client_id=YOUR_CLIENT_ID&direction=outbound&status=no-answer&from=2026-10-22T18:30:00Z&to=2026-10-23T18:30:00Z&limit=200'

# Calls from or to one number in the last 7 days
curl 'https://api.vocalstack.site/v1/calls?client_id=YOUR_CLIENT_ID&number=919876543210'

# One call
curl 'https://api.vocalstack.site/v1/calls/3f2b6c1e-8a4d-4c2e-9b1f-5d7e8a9c0b12?client_id=YOUR_CLIENT_ID'
```

</Tab>
<Tab value="Python">

Uses the `requests` package (`pip install requests`).

```python
import time
import requests

BASE_URL = "https://api.vocalstack.site"
CLIENT_ID = "YOUR_CLIENT_ID"

def api_get(path, params, tries=6):
    """GET with retries on 429 and temporary errors. Returns `data`, or None on 404."""
    for attempt in range(tries):
        last = attempt == tries - 1
        try:
            r = requests.get(BASE_URL + path, params=params, timeout=30)
        except requests.RequestException:
            if last:
                raise
        else:
            if r.status_code == 200:
                return r.json()["data"]
            if r.status_code == 404:
                return None
            if r.status_code != 429 and r.status_code < 500:
                raise RuntimeError(f"HTTP {r.status_code}: {r.text[:300]}")
            if last:
                raise RuntimeError(f"HTTP {r.status_code} after {tries} tries")
        time.sleep(min(2 ** attempt, 30))  # 1, 2, 4, 8, 16 s

def get_call(call_id):
    """One call, or None if your account has no call with this id (yet)."""
    return api_get(f"/v1/calls/{call_id}", {"client_id": CLIENT_ID})

def list_calls(start, end, **filters):
    """Every call recorded from `start` (included) to `end` (not included), newest first.
    start, end: times like "2026-10-01T00:00:00Z", at most 31 days apart.
    filters: direction=..., status=..., number=..."""
    params = {"client_id": CLIENT_ID, "from": start, "to": end, "limit": 200, **filters}
    while True:
        page = api_get("/v1/calls", params)
        yield from page["calls"]
        if not page["has_more"]:
            return
        params["cursor"] = page["next_cursor"]
        time.sleep(0.25)  # stay under 5 requests a second

if __name__ == "__main__":
    for call in list_calls("2026-10-01T00:00:00Z", "2026-10-08T00:00:00Z", direction="outbound"):
        print(call["call_id"], call["to"], call["status"], call["billed_seconds"], call["cost"])
```

</Tab>
<Tab value="JavaScript">

Node.js 18 or later. Save as `calls.mjs` and run `node calls.mjs`.

```js
const BASE_URL = "https://api.vocalstack.site";
const CLIENT_ID = "YOUR_CLIENT_ID";

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

// GET with retries on 429 and temporary errors. Resolves to `data`, or null on 404.
async function apiGet(path, params, tries = 6) {
  const url = `${BASE_URL}${path}?${new URLSearchParams(params)}`;
  for (let attempt = 0; attempt < tries; attempt++) {
    const last = attempt === tries - 1;
    let res;
    try {
      res = await fetch(url, { signal: AbortSignal.timeout(30_000) });
    } catch (err) {
      if (last) throw err;
    }
    if (res) {
      if (res.status === 200) return (await res.json()).data;
      if (res.status === 404) return null;
      if (res.status !== 429 && res.status < 500) {
        throw new Error(`HTTP ${res.status}: ${await res.text()}`);
      }
      if (last) throw new Error(`HTTP ${res.status} after ${tries} tries`);
      await res.body?.cancel(); // free the connection before retrying
    }
    await sleep(Math.min(2 ** attempt, 30) * 1000); // 1, 2, 4, 8, 16 s
  }
}

// One call, or null if your account has no call with this id (yet).
function getCall(callId) {
  return apiGet(`/v1/calls/${encodeURIComponent(callId)}`, { client_id: CLIENT_ID });
}

// Every call recorded from `from` (included) to `to` (not included), newest first.
// from, to: times like "2026-10-01T00:00:00Z", at most 31 days apart.
// filters: { direction, status, number }
async function* listCalls(from, to, filters = {}) {
  const params = { client_id: CLIENT_ID, from, to, limit: 200, ...filters };
  while (true) {
    const page = await apiGet("/v1/calls", params);
    yield* page.calls;
    if (!page.has_more) return;
    params.cursor = page.next_cursor;
    await sleep(250); // stay under 5 requests a second
  }
}

for await (const call of listCalls("2026-10-01T00:00:00Z", "2026-10-08T00:00:00Z", { direction: "outbound" })) {
  console.log(call.call_id, call.to, call.status, call.billed_seconds, call.cost);
}
```

</Tab>
</Tabs>

## 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:

1. List with `from` = the `to` of your previous run minus 2 minutes, and `to` = now. On the first run, start from the earliest time you need, reading it window by window (section 6).
2. Save each call by its `call_id`, replacing a call you already have. The 2-minute overlap then only brings calls you can recognise.
3. Once you have read every page, keep this run's `to` for the next run. If a run fails, run it again with the same `from`.

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).
