Skip to navigation

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

ParameterValuesNotes
limit1 to 100How many items per page. 20 by default.
cursoropaque textThe next_cursor value of the previous response, sent back unchanged. Absent for the first page.

Response shape

{
"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.
# 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"

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

RouteNotes
GET /v1/callsMost 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-requestsRegister 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.