Reference

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

ParameterTypeDefaultDescription
page_sizeinteger20Number of items per page. Minimum 1, maximum 100.
page_tokenstring(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:

FieldTypeDescription
(resource key)arrayThe items for this page. The key is the plural resource name — agents, calls, numbers, keys, conversations, etc.
next_page_tokenstringCursor to fetch the next page. Absent when there are no more pages.

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:

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

Response:

1{
2  "agents": [
3    {
4      "agent_id": "agt_k7m2n9p4q1",
5      "display_name": "Customer Support Agent",
6      "language": "en",
7      "created_at": "2026-04-01T10:00:00Z"
8    },
9    {
10      "agent_id": "agt_a1b2c3d4e5",
11      "display_name": "Sales Outreach Agent",
12      "language": "en",
13      "created_at": "2026-04-02T14:30:00Z"
14    }
15  ],
16  "next_page_token": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNC0wMlQxNDozMDowMFoiLCJpZCI6ImFndF9hMWIyYzNkNGU1In0"
17}

Iterating Pages

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

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

EndpointDescription
GET /v1/agentsList agents
GET /v1/numbersList provisioned numbers
GET /v1/numbers/availableList available numbers for provisioning
GET /v1/callsList calls
GET /v1/api-keysList API keys
GET /v1/conversationsList conversations
GET /v1/webhooks/deliveriesList webhook delivery history

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.