# Paginação Baseada em Cursor — Guia do next_page_token

> Os endpoints de lista na API v1 usam paginação opaca baseada em cursor — e não números de página — através de um next_page_token que você deve passar de volta exatamente como recebeu, sem nunca decodificar ou construir por conta própria.

Todo endpoint de lista na v1 (`GET /batches`, `GET /account/usage` e qualquer endpoint de lista futuro) é paginado da mesma forma: um cursor, não um número de página.

## O envelope da lista

Toda resposta de lista tem os mesmos três campos de nível superior:

```json
{
  "data": [ /* ... */ ],
  "has_more": true,
  "next_page_token": "eyJpZCI6IDQyfQ"
}
```

- `data` — o array de resultados desta página.
- `has_more` — indica se existe outra página após esta.
- `next_page_token` — passe este valor de volta como `?page_token=` na sua próxima requisição para obter a próxima página. Sempre é `null` quando `has_more` é `false` — os dois campos nunca entram em conflito.

## Por que um cursor, e não um número de página

Não existe paginação no estilo `?page=2` em nenhum lugar da v1, nem o parâmetro `offset`. Listas como seus lotes ou seu histórico de uso estão em constante mudança — novos lotes são concluídos, novas linhas de uso são gravadas — portanto, uma "página 2" baseada em deslocamento pode pular ou repetir linhas silenciosamente se algo for inserido entre suas requisições. Um cursor evita isso: cada token aponta para uma posição exata na ordenação subjacente, não para um deslocamento numérico mutável.

## O token é opaco

`next_page_token` não é um número de página, e sua codificação interna não faz parte do contrato — trate-o estritamente como uma string opaca. Passe-o exatamente como recebido; não o decodifique, não construa o seu próprio e não presuma que seu formato é estável entre versões da API. A única garantia é: passe o token que você recebeu, obtenha a próxima página.

## Exemplo: navegando pelos seus lotes

Primeira requisição, ainda sem token:

```bash
curl "https://imagetotable.ai/api/v1/batches?limit=20" \
  -H "Authorization: Bearer $API_KEY"
```

```json
{
  "data": [ { "batch_name": "260716-4K9P", "status": "succeeded", "document_count": 3, "created_at": "2026-07-16T09:12:03Z" } ],
  "has_more": true,
  "next_page_token": "eyJpZCI6IDQyfQ"
}
```

Próxima requisição, usando o token da resposta anterior:

```bash
curl "https://imagetotable.ai/api/v1/batches?limit=20&page_token=eyJpZCI6IDQyfQ" \
  -H "Authorization: Bearer $API_KEY"
```

Continue repetindo com o `next_page_token` de cada resposta até que `has_more` retorne `false`. Um token malformado ou expirado retorna um erro `invalid_parameter` (veja [Tratamento de Erros](/developers/guides/errors)) em vez de retornar silenciosamente a primeira página novamente — assim, um token corrompido é detectado imediatamente, em vez de reiniciar seu loop silenciosamente.

## O parâmetro `limit`

Todo endpoint de lista aceita um parâmetro de consulta `limit` opcional para controlar o tamanho da página, cada um com seu próprio padrão e máximo (veja a página do endpoint específico na [Referência da API](/developers/reference/) para seus limites exatos). Solicitar um `limit` fora do intervalo permitido retorna `invalid_parameter`.

---

Source: https://imagetotable.ai/pt/developers/guides/pagination