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

# Pagination

> How to paginate through list endpoints using cursor-based pagination.

Voicebip uses cursor-based pagination for all list endpoints. Cursor-based pagination provides stable, consistent results even when new records are created between requests.

## Parameters

| Parameter    | Type    | Default   | Description                                                                          |
| ------------ | ------- | --------- | ------------------------------------------------------------------------------------ |
| `page_size`  | integer | 20        | Number of items per page. Minimum 1, maximum 100.                                    |
| `page_token` | string  | *(empty)* | Opaque cursor from a previous response's `next_page_token`. Omit for the first page. |

## Response Format

Every list response includes a `next_page_token` field:

| Field             | Type   | Description                                                                                                                |
| ----------------- | ------ | -------------------------------------------------------------------------------------------------------------------------- |
| *(resource key)*  | array  | The items for this page. The key is the plural resource name — `agents`, `calls`, `numbers`, `keys`, `conversations`, etc. |
| `next_page_token` | string | Cursor to fetch the next page. **Absent when there are no more pages.**                                                    |

> **Note**
>
> The array key is the plural resource name, not `data`. For example, `GET /v1/agents` returns `{ "agents": [...], "next_page_token": "..." }`. Check the endpoint's response schema for the exact key.

## Example

Fetch the first page of agents with 10 items per page:

```bash
curl -X GET "https://api.voicebip.com/v1/agents?page_size=10" \
  -H "Authorization: Bearer pk_live_your_key"
```

Response:

```json
{
  "agents": [
    {
      "agent_id": "agt_k7m2n9p4q1",
      "display_name": "Customer Support Agent",
      "language": "en",
      "created_at": "2026-04-01T10:00:00Z"
    },
    {
      "agent_id": "agt_a1b2c3d4e5",
      "display_name": "Sales Outreach Agent",
      "language": "en",
      "created_at": "2026-04-02T14:30:00Z"
    }
  ],
  "next_page_token": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNC0wMlQxNDozMDowMFoiLCJpZCI6ImFndF9hMWIyYzNkNGU1In0"
}
```

## Iterating Pages

To retrieve all items, keep requesting the next page until `next_page_token` is absent. Here is a bash loop using `jq`:

```bash
API_KEY="pk_live_your_key"
BASE_URL="https://api.voicebip.com/v1"
PAGE_TOKEN=""

while true; do
  if [ -z "$PAGE_TOKEN" ]; then
    RESPONSE=$(curl -s "${BASE_URL}/agents?page_size=10" \
      -H "Authorization: Bearer ${API_KEY}")
  else
    RESPONSE=$(curl -s "${BASE_URL}/agents?page_size=10&page_token=${PAGE_TOKEN}" \
      -H "Authorization: Bearer ${API_KEY}")
  fi

  # Process the current page — key is the resource name ("agents" here)
  echo "$RESPONSE" | jq '.agents[]'

  # Extract the next page token
  PAGE_TOKEN=$(echo "$RESPONSE" | jq -r '.next_page_token // empty')

  # Stop if there is no next page
  if [ -z "$PAGE_TOKEN" ]; then
    echo "All pages fetched."
    break
  fi
done
```

## Endpoints Supporting Pagination

All of the following list endpoints accept `page_size` and `page_token`:

| Endpoint                      | Description                             |
| ----------------------------- | --------------------------------------- |
| `GET /v1/agents`              | List agents                             |
| `GET /v1/numbers`             | List provisioned numbers                |
| `GET /v1/numbers/available`   | List available numbers for provisioning |
| `GET /v1/calls`               | List calls                              |
| `GET /v1/api-keys`            | List API keys                           |
| `GET /v1/conversations`       | List conversations                      |
| `GET /v1/webhooks/deliveries` | List webhook delivery history           |

> **Note**
>
> The `page_token` is **opaque** -- do not parse, decode, or construct it. Always use the exact value from the `next_page_token` field. Cursors are not reusable across different queries. If you change `page_size` or filter parameters, start from the first page with no `page_token`.