Pagination | AgentPhone

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.

Parameter	Description
`limit`	Number of results per page (default: 20, max: 100)
`offset`	Number of results to skip (default: 0)

const BASE_URL = "https://api.agentphone.ai";
// Get first page (20 results)
const page1 = await fetch(`${BASE_URL}/v1/numbers?limit=20&offset=0`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});
// Get second page
const page2 = await fetch(`${BASE_URL}/v1/numbers?limit=20&offset=20`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});

Response format

{
  "data": [],
  "hasMore": true,
  "total": 42
}

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.

Parameter	Description
`limit`	Number of results per page (default: 50, max: 200)
`before`	ISO timestamp — return messages before this time
`after`	ISO timestamp — return messages after this time

const BASE_URL = "https://api.agentphone.ai";
// Get most recent 50 messages
const recent = await fetch(
  `${BASE_URL}/v1/numbers/${numberId}/messages?limit=50`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);
const messages = await recent.json();
const oldestMessage = messages.data[messages.data.length - 1];
// Get next 50 messages (older than the oldest we have)
if (messages.hasMore) {
  const older = await fetch(
    `${BASE_URL}/v1/numbers/${numberId}/messages?limit=50&before=${oldestMessage.receivedAt}`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  );
}

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.