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

# Paginação

> Como percorrer listagens da API: parâmetros, tetos por endpoint e como ler o total corretamente.

## Parâmetros

As listagens da API pública são paginadas por número de página:

| Parâmetro | Descrição                         |
| --------- | --------------------------------- |
| `page`    | Número da página. Começa em **1** |
| `limit`   | Quantos itens por página          |

```bash theme={null}
?page=2&limit=50
```

<Note>
  Alguns endpoints de relatório usam outro esquema — [Assinaturas Perdidas](/api-reference/subscriptions/churn), por exemplo, pagina por `limit` e `offset`. A página de referência de cada endpoint é sempre a palavra final sobre quais parâmetros ele aceita.
</Note>

## O teto de `limit` varia por endpoint

Não existe um teto único global. Cada listagem tem o seu:

| Comportamento | Teto de `limit`                                                                    | Onde aparece                        |
| ------------- | ---------------------------------------------------------------------------------- | ----------------------------------- |
| Padrão        | Sem teto explícito de override; a página vem com 10 itens quando `limit` é omitido | A maioria dos endpoints             |
| Ampliado      | Até **1000**                                                                       | Listagens como checkouts e clientes |
| Reduzido      | Até **500**                                                                        | Listagem de pedidos                 |

<Warning>
  Nunca presuma um teto fixo para a API inteira. Pedir `limit` acima do teto do endpoint não devolve mais itens — a listagem é limitada ao máximo daquele endpoint.
</Warning>

Se você usa o [CaktoMCP](/mcp/visao-geral), `cakto_get_endpoint` mostra o teto real da operação consultada, direto do contrato.

## O formato da resposta

Toda listagem devolve o mesmo envelope:

```json theme={null}
{
  "count": 348,
  "next": "https://api.cakto.com.br/public_api/orders/?page=2",
  "previous": null,
  "results": [...]
}
```

| Campo      | O que é                                                       |
| ---------- | ------------------------------------------------------------- |
| `count`    | Total de itens que atendem ao filtro, em **todas** as páginas |
| `next`     | URL absoluta da próxima página, ou `null` na última           |
| `previous` | URL absoluta da página anterior, ou `null` na primeira        |
| `results`  | Os itens **desta** página                                     |

<Warning>
  Para saber o tamanho total do conjunto, use `count`. Contar `results` devolve apenas o tamanho da página atual — com `limit=50` e 348 pedidos, `results` tem 50 itens e `count` tem 348.
</Warning>

Para percorrer tudo, repita a chamada incrementando `page` enquanto `next` não for `null`.

## Pelo CaktoMCP

O `cakto_call` nunca repassa `next`/`previous` crus — são URLs absolutas que o agente não sabe abrir sozinho. O envelope é traduzido para:

```json theme={null}
{
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 348,
    "has_more": true,
    "next_page": 2
  }
}
```

Aqui vale a mesma regra: o total é `pagination.total`, nunca o tamanho de `results`. Para listar tudo, repita a chamada com `query.page` igual a `next_page` enquanto `has_more` for `true`.

Respostas muito grandes são truncadas — teto de cerca de 50 itens ou 40 KB —, sempre com um aviso em `notes` dizendo quanto foi cortado e como estreitar o filtro. O corte nunca é silencioso. Detalhes em [Ferramentas de Execução](/mcp/ferramentas-de-execucao).

## Próximos passos

<CardGroup cols={2}>
  <Card title="Introdução" icon="book-open" href="/introduction">
    Busca, filtros e ordenação nas listagens
  </Card>

  <Card title="Limites de Requisição" icon="gauge-high" href="/conceitos/rate-limits">
    Quantas páginas você pode pedir por minuto
  </Card>
</CardGroup>