# Pagination (/pagination)

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 [#which-list-uses-which-style]

| Endpoint | Style | `limit` default / max | Total count | Order |
| --- | --- | --- | --- | --- |
| [`GET /api/v1/leads/`](/api-reference/leads/listLeads) | 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/`](/api-reference/calls/listCalls) | Page or cursor | 25 / 200 | Capped at 10,000 | Newest first (`createdAt`, then `id`) |
| [`GET /api/v1/campaigns/`](/api-reference/campaigns/listCampaigns) | Page | 25 / 200 | Exact | Newest first (`createdAt`, then `id`) |
| [`GET /api/v1/campaigns/{campaign_id}/leads`](/api-reference/campaigns/listCampaignLeads) | Page (optional) | 50 / 200 | Exact | Newest lead first, then `id` |
| [`GET /api/v1/tickets/`](/api-reference/tickets/listTickets) | Page | 25 / 200 | Capped at 10,000 | Your sort, then `id` |
| [`GET /api/v1/callbacks`](/api-reference/campaigns/listCallbacks) | Offset | 50 / 200 | Exact (`total`) | Soonest `dialAt` first |
| [`GET /api/v1/leads/{lead_id}/timeline`](/api-reference/leads/getLeadTimeline) | Cursor | 30 / 100 | — | Newest first |
| [`GET /api/v1/leads/{lead_id}/notes`](/api-reference/lead-notes/listLeadNotes) | Cursor | 30 / 50 | `notesCount` | Newest first, pinned notes on the first page |
| [`GET /api/v1/webhook-deliveries/`](/api-reference/webhooks/listWebhookDeliveries) | Cursor | 25 / 100 | — | Newest first |
| [`GET /api/v1/leads/dnc`](/api-reference/do-not-call/listDoNotCall) | 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 [#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:

```json
{
  "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` [#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 [#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`.

```json
{
  "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`](/errors/parameter_invalid).

### Leads and calls [#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.

<Tabs groupId="language" persist items={["Node.js","Python"]}>
<Tab value="Node.js">
```js
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;
  }
}
```
</Tab>

<Tab value="Python">
```python
import os, requests

def all_leads():
    cursor = ""
    while True:
        res = requests.get(
            "https://api.callmitra.ai/api/v1/leads/",
            headers={"X-API-Key": os.environ["CALLMITRA_API_KEY"]},
            params={"limit": 200, "cursor": cursor},
            timeout=30,
        )
        body = res.json()
        yield from body["leads"]
        if not body.get("hasMore") or not body.get("nextCursor"):
            return
        cursor = body["nextCursor"]
```
</Tab>
</Tabs>

### Ticket activity [#ticket-activity]

[`GET /api/v1/tickets/{ticket_id}/activities`](/api-reference/tickets/listTicketActivities) 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 [#offset-lists]

[`GET /api/v1/callbacks`](/api-reference/campaigns/listCallbacks) 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 [#capped-lists]

[`GET /api/v1/leads/dnc`](/api-reference/do-not-call/listDoNotCall) 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 [#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](/rate-limits).