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.

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 be cached and may not be present on every endpoint). Use hasMore for traversal.

Not every endpoint uses this envelope: master webhook deliveries return {items, total, offset, limit}, and per-agent delivery history returns an array. Consult the endpoint reference before writing a shared pagination helper.

Cursor-Based Pagination

Used by message endpoints like GET /v1/numbers/:id/messages. Cursors are ISO 8601 timestamps, not message IDs. Results are newest first. Supply before to page backward or after to fetch newer messages; do not supply both. The comparisons are strict. A timestamp is not a unique message cursor, so this interface cannot guarantee a lossless export when a page boundary splits messages sharing the exact same timestamp.

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 && oldestMessage) {
  const older = await fetch(
    `${BASE_URL}/v1/numbers/${numberId}/messages?limit=50&before=${encodeURIComponent(oldestMessage.receivedAt)}`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  );
}