Pagination

Every endpoint that returns a collection — agents, contacts, calls, and the like — is paginated. Rather than offset/page numbers, Vantax uses cursor-based pagination: you walk through results by pointing at the last object you have seen. Because the cursor is a real object id, results don't shift or duplicate when records are added or removed mid-iteration, the way they can with offset paging.

Request parameters

Paginated endpoints accept two optional query parameters, passed in the URL query string:

• limit — the number of items to return per page. Defaults to 20 and may not exceed 100. Values above the maximum are clamped to 100.
• starting_after — a cursor for use in pagination. It is the id of an object (for example agt_3d9b21). The page returned will contain the items that come after that object in the result ordering. Omit it to fetch the first page.

A request for the page following agent agt_3d9b21:

curl "https://api.vantaxai.com/v1/agents?limit=20&starting_after=agt_3d9b21" \
  -H "Authorization: Bearer vx_live_3fa9c2..."

Response shape

List responses follow the standard envelope: data holds the array of items for the current page, and a pagination object describes the result set.

{
  "success": true,
  "data": [
    { "id": "agt_4f8c02", "name": "Front Desk", "created_at": "2026-05-14T09:21:00Z" },
    { "id": "agt_5a1d77", "name": "Billing Support", "created_at": "2026-05-13T17:04:00Z" }
    // … up to `limit` items
  ],
  "pagination": {
    "total": 142,
    "limit": 20,
    "has_more": true,
    "next_cursor": "agt_5a1d77"
  }
}

The pagination object contains:

• total — the total number of items across all pages that match the request.
• limit — the effective page size applied to this response (after any clamping).
• has_more — true when further pages remain. Keep paging while this is true; stop when it is false.
• next_cursor — when present, the id to pass as starting_after on your next request. It is equivalent to the id of the last item in data, provided for convenience.

Paging through results

To collect an entire result set, request the first page, then keep passing the id of the last item you received as starting_after until has_more is false. The loop below uses the maximum page size to minimize round trips:

const BASE = "https://api.vantaxai.com/v1";
const headers = { Authorization: "Bearer vx_live_3fa9c2..." };

async function listAllAgents() {
  const agents = [];
  let startingAfter = null;

  while (true) {
    const url = new URL(`${BASE}/agents`);
    url.searchParams.set("limit", "100");
    if (startingAfter) url.searchParams.set("starting_after", startingAfter);

    const res = await fetch(url, { headers });
    const body = await res.json();

    agents.push(...body.data);

    if (!body.pagination.has_more) break;

    // Advance the cursor to the id of the last item we received.
    startingAfter = body.data[body.data.length - 1].id;
  }

  return agents;
}

Best practices

• Drive the loop with has_more. Don't infer the end of the set from a short page or from total arithmetic — a page can be short and still have more results. Stop only when has_more is false.
• Use a larger limit for bulk reads. Fetching 100 items per page reduces the number of requests and the time spent paging through large collections.
• Treat cursors as opaque object ids.Pass back exactly what the API gave you. Don't construct, decode, or modify a cursor — its format is an object id today and should not be parsed.
• Persist cursors to resume. For long-running or interrupted jobs, store the last cursor you processed so you can pick up where you left off rather than re-reading from the first page.
• Keep filters constant across pages. Any query filters must stay identical on every request in the sequence; starting_after only makes sense within a single, consistent query.
• Be mindful of rate limits. When paging through many results, handle 429responses with backoff so a large iteration doesn't exhaust your quota.