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:
pageandlimit, with apaginationobject. - Cursor: pass back the
nextCursoryou received. Leads and calls support both styles. - Offset:
limitandoffset(callbacks). - One response: small lists that return everything at once.
Which list uses which style
| Endpoint | Style | limit default / max | Total count | Order |
|---|---|---|---|---|
GET /api/v1/leads/ | Page or cursor | 25 / 200 | Capped at 10,000, exact with includeTotal=true | Newest first (createdAt, then id), or your sortBy |
GET /api/v1/calls/ | Page or cursor | 25 / 200 | Capped at 10,000 | Newest first (createdAt, then id) |
GET /api/v1/campaigns/ | Page | 25 / 200 | Exact | Newest first (createdAt, then id) |
GET /api/v1/campaigns/{campaign_id}/leads | Page (optional) | 50 / 200 | Exact | Newest lead first, then id |
GET /api/v1/tickets/ | Page | 25 / 200 | Capped at 10,000 | Your sort, then id |
GET /api/v1/callbacks | Offset | 50 / 200 | Exact (total) | Soonest dialAt first |
GET /api/v1/leads/{lead_id}/timeline | Cursor | 30 / 100 | — | Newest first |
GET /api/v1/leads/{lead_id}/notes | Cursor | 30 / 50 | notesCount | Newest first, pinned notes on the first page |
GET /api/v1/webhook-deliveries/ | Cursor | 25 / 100 | — | Newest first |
GET /api/v1/leads/dnc | One response, up to 500 | — | Entries returned | Most 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
| Parameter | Default | Notes |
|---|---|---|
page | 1 | 1-based page number. |
limit | see table | Items 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,
totalItemsis10000andtotalCappedistrue. Show it as "10,000+". totalPagesis then based on 10,000, andhasNextPagestaystruewhile pages come back full. Loop onhasNextPage, not ontotalPages.- On leads, send
includeTotal=trueto 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
cursorasks for the first page in cursor mode. - In cursor mode the count is skipped, so it stays fast however deep you go.
paginationholds onlyitemsPerPage,hasNextPageandnextCursor. - On leads,
cursorworks only with the default sort (newest first). With anothersortByyou get422parameter_invalid; usepageinstead. - 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, sototalItemscounts 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
limitand stay within your rate limit.