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

# Paginate list endpoints with cursors

> List endpoints use one of three paging shapes: cursor pages with a next_cursor, offset pages with has_more, and complete lists. Which endpoint uses which.

List endpoints use one of three shapes. Each endpoint's reference page says which it uses.

## Cursor pages

Used by conversations, messages and widget threads.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": [ ... ],
  "next_cursor": "eyJvIjoyMH0",
  "has_more": true
}
```

Pass `limit` to size the page, and pass the previous response's `next_cursor` as `cursor` to get the next page. Keep going while `has_more` is `true`; do not infer the end from a short page.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
import requests

BASE = f"{os.environ['MITHUNAI_URL']}/arukz/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['MITHUNAI_API_KEY']}"}


def all_conversations():
    params = {"limit": 50}
    while True:
        page = requests.get(f"{BASE}/conversations", headers=HEADERS, params=params, timeout=30).json()
        yield from page["data"]
        if not page["has_more"]:
            return
        params["cursor"] = page["next_cursor"]
```

Treat cursors as opaque strings.

## Offset pages

Used by documents.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": [ ... ],
  "total": 342,
  "limit": 50,
  "offset": 100,
  "has_more": true
}
```

Increase `offset` by `limit` for each page while `has_more` is `true`.

## Unpaged lists

Assistants, knowledge sources, ingestion jobs, collections, API keys and widget deployments return their items without a cursor, in a `data` array. Widget deployments use a `deployments` array instead. Assistants, ingestion jobs, API keys and widget deployments accept `limit`; knowledge sources and collections always return every item. See each endpoint.

## Limits

An over-large `limit` is handled one of two ways, depending on the endpoint:

* **Refused** with `400`: conversations, messages, assistants, API keys and widget deployments.
* **Reduced** to the maximum of 100: ingestion jobs and documents.

Each endpoint's page gives its default and maximum.