For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
HomeGet API key
DocumentationIntegrationsAPI Reference
DocumentationIntegrationsAPI Reference
  • Get Started
    • Welcome
  • Guides
    • Agents
    • Phone Numbers
    • Conversations
    • Calls
    • Webhooks
    • Agent Webhooks
    • Usage & Billing
  • Reference
    • Pagination
    • Error Handling
    • Messaging Rate Limits
    • Testing
    • Best Practices
    • Code Examples
    • FAQ
  • SDKs
    • TypeScript / JavaScript
    • Python
LogoLogo
HomeGet API key
On this page
  • Offset-Based Pagination
  • Response format
  • Cursor-Based Pagination
Reference

Pagination

Was this page helpful?
Previous

Error Handling

Next
Built with

Most list endpoints support pagination to efficiently retrieve large datasets. The API uses two pagination strategies depending on the endpoint.

Offset-Based Pagination

Used by endpoints like GET /v1/numbers, GET /v1/conversations, and GET /v1/agents.

ParameterDescription
limitNumber of results per page (default: 20, max: 100)
offsetNumber of results to skip (default: 0)
1const BASE_URL = "https://api.agentphone.ai";
2
3// Get first page (20 results)
4const page1 = await fetch(`${BASE_URL}/v1/numbers?limit=20&offset=0`, {
5  headers: { Authorization: `Bearer ${API_KEY}` },
6});
7
8// Get second page
9const page2 = await fetch(`${BASE_URL}/v1/numbers?limit=20&offset=20`, {
10  headers: { Authorization: `Bearer ${API_KEY}` },
11});

Response format

1{
2  "data": [],
3  "hasMore": true,
4  "total": 42
5}
  • hasMore — true if more results are available beyond the current page.
  • total — Total number of items (may not be present on every endpoint).

Cursor-Based Pagination

Used by message endpoints like GET /v1/numbers/:id/messages. Cursors use timestamps for efficient pagination of time-ordered data.

ParameterDescription
limitNumber of results per page (default: 50, max: 200)
beforeISO timestamp — return messages before this time
afterISO timestamp — return messages after this time
1const BASE_URL = "https://api.agentphone.ai";
2
3// Get most recent 50 messages
4const recent = await fetch(
5  `${BASE_URL}/v1/numbers/${numberId}/messages?limit=50`,
6  { headers: { Authorization: `Bearer ${API_KEY}` } }
7);
8
9const messages = await recent.json();
10const oldestMessage = messages.data[messages.data.length - 1];
11
12// Get next 50 messages (older than the oldest we have)
13if (messages.hasMore) {
14  const older = await fetch(
15    `${BASE_URL}/v1/numbers/${numberId}/messages?limit=50&before=${oldestMessage.receivedAt}`,
16    { headers: { Authorization: `Bearer ${API_KEY}` } }
17  );
18}

Always check hasMore before fetching the next page. Use cursor-based pagination (before/after) for time-ordered data — it is more efficient than offset-based pagination for large datasets.