Paginação

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:

{
  "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:

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

{
  "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:

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) 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 para seus limites exatos). Solicitar um limit fora do intervalo permitido retorna invalid_parameter.