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

# Pagination

> Learn how cursor pagination works in the Chief Public API.

## Overview

Several Chief API list endpoints use **cursor-based pagination** so you can walk large datasets without offset drift. Paginated responses include:

| Field      | Description                                             |
| ---------- | ------------------------------------------------------- |
| `data`     | Items in this page.                                     |
| `first_id` | Id of the first item in this page (omitted when empty). |
| `last_id`  | Id of the last item in this page (omitted when empty).  |
| `has_more` | `true` when another page exists after this one.         |

Use resource ids as cursors. The cursor id is **excluded** from the next page (the page starts strictly after or before that id).

## Supported endpoints

| Endpoint         | Pagination                                             |
| ---------------- | ------------------------------------------------------ |
| `GET /v1/chats`  | Cursor (`after_id`, `before_id`, `limit`)              |
| `GET /v1/assets` | Cursor (`after_id`, `before_id`, `limit`)              |
| `GET /v1/labels` | Returns full list in v1 (`has_more` is always `false`) |

## Parameters

All cursor-paginated endpoints accept:

<ParamField query="limit" type="integer" default="25">
  Maximum items per page. Minimum `1`, maximum `100`.
</ParamField>

<ParamField query="after_id" type="string">
  Resource id from the previous response's `last_id`. Returns items strictly **after** this id. Omit on the first request. Mutually exclusive with `before_id`.
</ParamField>

<ParamField query="before_id" type="string">
  Resource id to paginate backward from. Returns items strictly **before** this id. Mutually exclusive with `after_id`.
</ParamField>

## Response format

```json theme={null}
{
  "data": [
    { "chat_id": "chat_d8aad64dib2c7m3ae7j0", "created_at": "2026-05-23T10:15:30Z" },
    { "chat_id": "chat_d8aad64dib2c7m3ae7j1", "created_at": "2026-05-23T10:16:00Z" }
  ],
  "first_id": "chat_d8aad64dib2c7m3ae7j0",
  "last_id": "chat_d8aad64dib2c7m3ae7j1",
  "has_more": true
}
```

Chats are returned **newest first**. Assets follow the same list envelope.

## Forward pagination

Pass `last_id` from the current page as `after_id` on the next request when `has_more` is `true`:

```bash theme={null}
# First page
curl -sS "$CHIEF_BASE_URL/v1/chats?limit=25" \
  -H "X-API-Key: $CHIEF_API_KEY" \
  -H "X-Project-Id: $CHIEF_PROJECT_ID"

# Next page
curl -sS "$CHIEF_BASE_URL/v1/chats?limit=25&after_id=chat_d8aad64dib2c7m3ae7j1" \
  -H "X-API-Key: $CHIEF_API_KEY" \
  -H "X-Project-Id: $CHIEF_PROJECT_ID"
```

## Backward pagination

Pass `first_id` from the current page as `before_id` to walk toward older items:

```bash theme={null}
curl -sS "$CHIEF_BASE_URL/v1/chats?limit=25&before_id=chat_d8aad64dib2c7m3ae7j0" \
  -H "X-API-Key: $CHIEF_API_KEY" \
  -H "X-Project-Id: $CHIEF_PROJECT_ID"
```

## Best practices

* Check `has_more` before requesting another page.
* Choose a `limit` that fits your use case (smaller for UI lists, larger for batch exports).
* Do not send `after_id` and `before_id` in the same request.

## Related

* [Introduction](/api-reference/introduction)
* [Errors](/api-reference/errors)
* **API reference → Chats** — `GET /v1/chats`
* **API reference → Assets** — `GET /v1/assets`