> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getvoxai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getvoxai.com/_mcp/server.

# Pagination

v1 lists use cursor pagination. There are no page numbers and no total: each response gives you a cursor to read the next page.

## Parameters

| Parameter | Values      | Notes                                                                                             |
| --------- | ----------- | ------------------------------------------------------------------------------------------------- |
| `limit`   | 1 to 100    | How many items per page. 20 by default.                                                           |
| `cursor`  | opaque text | The `next_cursor` value of the previous response, sent back unchanged. Absent for the first page. |

## Response shape

```json
{
  "data": [
    { "object": "call", "id": "call-3", "…": "…" }
  ],
  "has_more": true,
  "next_cursor": "eyJ2IjoxLC…"
}
```

* `data`: the items of the page.
* `has_more`: `true` if there are more items after this page.
* `next_cursor`: the cursor to pass to the next request, or `null` when there are no more.

## How to read a list

1. Make the first request without `cursor`.
2. If `has_more` is `true`, repeat the request with `cursor` set to `next_cursor`, **keeping the same filters and the same `order`**.
3. Stop when `has_more` is `false`.

#### curl

```bash
# First page
curl "https://api.getvoxai.com/v1/calls?limit=50" \
  -H "Authorization: Bearer $VOXAI_API_KEY"

# Next page
curl "https://api.getvoxai.com/v1/calls?limit=50&cursor=eyJ2IjoxLC…" \
  -H "Authorization: Bearer $VOXAI_API_KEY"
```

#### Node.js

```js
async function* allCalls() {
  let cursor;
  do {
    const url = new URL("https://api.getvoxai.com/v1/calls");
    url.searchParams.set("limit", "100");
    if (cursor) url.searchParams.set("cursor", cursor);

    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.VOXAI_API_KEY}` },
    });
    if (!response.ok) throw new Error(`Error ${response.status}`);

    const page = await response.json();
    yield* page.data;
    cursor = page.has_more ? page.next_cursor : undefined;
  } while (cursor);
}

for await (const call of allCalls()) {
  console.log(call.id);
}
```

#### Python

```python
import os
import requests

def all_calls():
    cursor = None
    while True:
        params = {"limit": 100}
        if cursor:
            params["cursor"] = cursor
        response = requests.get(
            "https://api.getvoxai.com/v1/calls",
            params=params,
            headers={"Authorization": f"Bearer {os.environ['VOXAI_API_KEY']}"},
            timeout=30,
        )
        response.raise_for_status()
        page = response.json()
        yield from page["data"]
        if not page["has_more"]:
            return
        cursor = page["next_cursor"]

for call in all_calls():
    print(call["id"])
```

## The cursor is opaque

Do not read it and do not build it: its format can change. Send it back exactly as you received it. A cursor belongs to the list and the order that produced it:

* used on another list, or after changing `order`, it is `400 invalid_cursor`;
* tampered with or malformed, it is `400 invalid_cursor`.

In these cases start again from the first page.

## Cursor lists

| Route                                                | Notes                                                                                       |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `GET /v1/calls`                                      | Most recent first. The `order` parameter (`desc` by default, or `asc`) sorts by start time. |
| `GET /v1/agents`                                     |                                                                                             |
| `GET /v1/knowledge/documents`                        |                                                                                             |
| `GET /v1/campaigns`                                  |                                                                                             |
| `GET /v1/campaigns/{campaign_id}/contacts`           |                                                                                             |
| `GET /v1/caller-requests`                            | Register of Caller requests.                                                                |
| `GET /v1/webhook-endpoints`                          |                                                                                             |
| `GET /v1/webhook-endpoints/{endpoint_id}/deliveries` |                                                                                             |

`GET /v1/lines` answers with the same shape, but `has_more` is always `false`.

## Good practices

* Use `limit=100` to read many items with fewer requests.
* Call lists can serve a cached response for a few seconds: a call that just ended can appear with a short delay.
* To sync one of your systems, do not rely on a total: read until `has_more` is `false` and deduplicate on `id`.