Skip to Content
CallMitraDocs

Pagination

Page through list endpoints with page numbers, a cursor, or an offset.

List endpoints return results in pages. Each list uses one of four styles:

  • Page number: page and limit, with a pagination object.
  • Cursor: pass back the nextCursor you received. Leads and calls support both styles.
  • Offset: limit and offset (callbacks).
  • One response: small lists that return everything at once.

Which list uses which style

EndpointStylelimit default / maxTotal countOrder
GET /api/v1/leads/Page or cursor25 / 200Capped at 10,000, exact with includeTotal=trueNewest first (createdAt, then id), or your sortBy
GET /api/v1/calls/Page or cursor25 / 200Capped at 10,000Newest first (createdAt, then id)
GET /api/v1/campaigns/Page25 / 200ExactNewest first (createdAt, then id)
GET /api/v1/campaigns/{campaign_id}/leadsPage (optional)50 / 200ExactNewest lead first, then id
GET /api/v1/tickets/Page25 / 200Capped at 10,000Your sort, then id
GET /api/v1/callbacksOffset50 / 200Exact (total)Soonest dialAt first
GET /api/v1/leads/{lead_id}/timelineCursor30 / 100—Newest first
GET /api/v1/leads/{lead_id}/notesCursor30 / 50notesCountNewest first, pinned notes on the first page
GET /api/v1/webhook-deliveries/Cursor25 / 100—Newest first
GET /api/v1/leads/dncOne response, up to 500—Entries returnedMost recently updated first

Agents, phone numbers, SIP trunks, tools, voices, the lead fields catalogue, ticket categories and teams, webhook endpoints and WhatsApp templates are returned in one response with no paging.

Page-number lists

ParameterDefaultNotes
page11-based page number.
limitsee tableItems per page. A larger value returns 422.

The response carries the items and a pagination object:

{
  "success": true,
  "leads": [{ "id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed", "name": "Asha Rao" }],
  "pagination": {
    "currentPage": 1,
    "totalPages": 8,
    "totalItems": 187,
    "totalCapped": false,
    "itemsPerPage": 25,
    "hasNextPage": true,
    "hasPreviousPage": false,
    "nextCursor": "eyJ0IjoiMjAyNi0xMS0xNVQxMDozMDowMFoiLCJpZCI6Ij…"
  },
  "hasMore": true,
  "nextCursor": "eyJ0IjoiMjAyNi0xMS0xNVQxMDozMDowMFoiLCJpZCI6Ij…"
}

Keep requesting page + 1 while hasNextPage (or the top-level hasMore) is true.

Large counts: totalCapped and includeTotal

Counting millions of rows is slow, so leads, calls and tickets stop counting at 10,000:

  • When more than 10,000 rows match, totalItems is 10000 and totalCapped is true. Show it as "10,000+".
  • totalPages is then based on 10,000, and hasNextPage stays true while pages come back full. Loop on hasNextPage, not on totalPages.
  • On leads, send includeTotal=true to get the exact count. It is slower on large workspaces.

Campaigns and campaign leads always return an exact count. GET /api/v1/campaigns/{campaign_id}/leads returns currentPage, totalItems, itemsPerPage, hasNextPage and hasPreviousPage only, and returns every lead in one response when you omit page.

Cursor lists

Pass the nextCursor from one response as cursor on the next request. You have reached the end when hasMore is false and nextCursor is null.

{
  "success": true,
  "items": [{ "id": "…", "type": "call" }],
  "hasMore": true,
  "nextCursor": "eyJ0IjoiMjAyNi0xMS0xNVQxMDozMDowMFoiLCJpZCI6Ij…"
}

A cursor is an opaque string: do not parse it or build one yourself. An invalid cursor returns 422 parameter_invalid.

Leads and calls

GET /api/v1/leads/ and GET /api/v1/calls/ accept cursor (up to 200 characters) as well as page:

  • An empty cursor asks for the first page in cursor mode.
  • In cursor mode the count is skipped, so it stays fast however deep you go. pagination holds only itemsPerPage, hasNextPage and nextCursor.
  • On leads, cursor works only with the default sort (newest first). With another sortBy you get 422 parameter_invalid; use page instead.
  • A page-number request on the default sort also returns nextCursor, so you can switch to cursor mode after the first page.

Prefer the cursor for full exports. Rows created while you read do not shift later pages.

async function* allLeads() {
  let cursor = '';
  while (true) {
    const url = new URL('https://api.callmitra.ai/api/v1/leads/');
    url.searchParams.set('limit', '200');
    url.searchParams.set('cursor', cursor);
    const res = await fetch(url, { headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY } });
    const body = await res.json();
    yield* body.leads;
    if (!body.hasMore || !body.nextCursor) return;
    cursor = body.nextCursor;
  }
}

Ticket activity

GET /api/v1/tickets/{ticket_id}/activities pages backwards: pass the activitiesCursor you received as before to load older activity, while hasOlderActivities is true. limit defaults to 50, up to 200.

Offset lists

GET /api/v1/callbacks takes limit (default 50, 1 to 200) and offset (default 0) and returns { "callbacks": [...], "total": 12 }. Add limit to offset until offset reaches total. Callbacks with the same dialAt have no fixed order between them, so a callback can move across a page boundary; filter by dateFrom and dateTo for exact windows.

Capped lists

GET /api/v1/leads/dnc returns up to 500 entries, most recently updated first. total is the number of entries in the response, and hasMore is true when your list holds more than 500.

Tips

  • Collection paths end with a slash (/api/v1/leads/). Without it the API answers with a redirect to the slash form.
  • Filters (search, status, campaignId, …) apply before pagination, so totalItems counts the filtered set.
  • Every list except callbacks ends its order on id, so rows with the same timestamp keep a fixed order and page boundaries do not overlap.
  • For a full export, use the largest limit and stay within your rate limit.

On this page