> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> How to walk a list endpoint to the end, which field to follow, and the two that are always null.

Follow `next_cursor`. Send it back as `cursor` on the next call, and stop when the response omits it.

```bash cURL theme={null}
curl -X POST "https://api.mixpeek.com/v1/collections/list?limit=100" \
  -H "Authorization: Bearer YOUR_MIXPEEK_API_KEY" \
  -H "X-Namespace: ns_your_namespace_id"

# then, for each subsequent page:
curl -X POST "https://api.mixpeek.com/v1/collections/list?limit=100&cursor=CURSOR_FROM_LAST_RESPONSE" \
  -H "Authorization: Bearer YOUR_MIXPEEK_API_KEY" \
  -H "X-Namespace: ns_your_namespace_id"
```

<Warning>
  **`next_page` and `previous_page` are always `null`.** They are deprecated and no endpoint populates them.

  A loop that treats `next_page: null` as "last page" stops after the first page and reads as a completed walk. That is the failure this page exists to prevent: a namespace with 130 collections returning its first 100 and nothing signalling that 30 were missed.
</Warning>

## The response object

| Field                              | Follow it?                                                               |
| ---------------------------------- | ------------------------------------------------------------------------ |
| `next_cursor`                      | **Yes.** Send it back as `cursor`. Absent means you have reached the end |
| `total`                            | Only present when you ask for it with `include_total=true`               |
| `page`, `page_size`, `total_pages` | Present alongside `total`, on the same condition                         |
| `next_page`, `previous_page`       | Never. Always `null`                                                     |

## Request parameters

Every list endpoint accepts all of these as query parameters. Pick one style and keep to it.

| Parameter              | Means                                                                       |
| ---------------------- | --------------------------------------------------------------------------- |
| `cursor`               | Where to resume. The value comes from the previous response's `next_cursor` |
| `next_cursor`, `after` | Aliases for `cursor`. If you send `cursor` too, `cursor` wins               |
| `limit`                | How many items to return                                                    |
| `page_size`            | Alias for `limit`                                                           |
| `offset`               | Skip this many items                                                        |
| `page`                 | Alias for `offset`, in pages rather than items                              |
| `include_total`        | Defaults to `false`. Setting it adds a count, and 50 to 200ms               |

<Tip>
  `next_cursor` and `after` are accepted as aliases specifically because the response calls the field `next_cursor`, so sending it straight back is the natural thing to do. An undeclared query parameter is dropped silently before any handler sees it, which is what made an earlier version of this loop run forever.
</Tip>

## Walking a list to the end

```python Python theme={null}
cursor = None
items = []

while True:
    params = {"limit": 100}
    if cursor:
        params["cursor"] = cursor
    page = client.collections.list(**params)

    items.extend(page["results"])
    cursor = page.get("pagination", {}).get("next_cursor")
    if not cursor:
        break
```

The termination condition is the absence of `next_cursor`, not `next_page`, and not an empty result set. A page can be short without being last.

## Related

<CardGroup cols={2}>
  <Card title="Filters" icon="filter" href="/docs/retrieval/filters">
    Narrowing a list before you page through it.
  </Card>

  <Card title="Rate limits" icon="gauge" href="/docs/operations/rate-limits-quotas">
    What a tight pagination loop counts against.
  </Card>
</CardGroup>