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

# Paginação

> Um esquema de cursor em todas as coleções.

Toda coleção devolve o mesmo envelope:

```json theme={null}
{
  "data": [ ... ],
  "meta": { "limit": 25, "has_more": true },
  "links": { "next": "https://api.chatsailer.com/v1/contacts?limit=25&cursor=eyJvZmZ..." }
}
```

Leia páginas seguindo `links.next` até ele ser `null`:

```python theme={null}
url = "https://api.chatsailer.com/v1/contacts?limit=100"
headers = {"Authorization": f"Bearer {token}"}

while url:
    page = httpx.get(url, headers=headers).json()
    for contact in page["data"]:
        handle(contact)
    url = page["links"]["next"]
```

## Trate o cursor como opaco

Não parseie, construa nem armazene um cursor. O conteúdo é um detalhe de
implementação e vai mudar quando os endpoints passarem para paginação por
keyset — mas `links.next` continua funcionando, que é o ponto de te entregar
uma URL em vez de um offset.

Passar um cursor que você mesmo montou, ou um de outro endpoint, devolve
`400 invalid_cursor`.

## Não há um total

A resposta diz se existe outra página (`meta.has_more`), não quantos
registros existem no total. Contar o conjunto filtrado significaria um segundo
scan completo em cada página, que fica mais lento exatamente quando o
workspace cresce.

Se você precisa de uma contagem, pagine e conte o que receber.

## Ordenação

Passe `sort` para ordenar uma coleção, por exemplo `sort=-created_at` para os
mais novos primeiro. Mantenha `sort` idêntico em cada página de um mesmo
percurso — mudá-lo no meio invalida o cursor.

## Como escolher um limit

`limit` tem default 25 e aceita até 100. Páginas maiores significam menos
round trips; páginas menores, respostas individuais mais rápidas. Para um
sync em massa, 100 costuma ser o certo.