Reference

Pagination

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.to";
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.to";
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.