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:

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

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.