Paginación

Cada endpoint de lista en v1 (GET /batches, GET /account/usage y cualquier otro endpoint de lista futuro) se pagina de la misma forma: un cursor, no un número de página.

El envolvente de lista

Toda respuesta de lista tiene los mismos tres campos de nivel superior:

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

• data — el arreglo de resultados de esta página.
• has_more — indica si existe otra página después de esta.
• next_page_token — devuélvalo como ?page_token= en su próxima solicitud para obtener la página siguiente. Siempre es null cuando has_more es false; ambos campos nunca discrepan.

Por qué un cursor, no un número de página

No existe paginación estilo ?page=2 en ninguna parte de v1, ni un parámetro offset. Listas como sus lotes o su historial de uso cambian constantemente — se completan nuevos lotes, se escriben nuevas filas de uso — por lo que una "página 2" basada en desplazamiento puede omitir o repetir filas silenciosamente si algo se inserta entre sus solicitudes. Un cursor evita eso: cada token apunta a una posición exacta en el orden subyacente, no a un desplazamiento numérico cambiante.

El token es opaco

next_page_token no es un número de página, y su codificación interna no forma parte del contrato — trátelo estrictamente como una cadena opaca. Devuélvalo exactamente como lo recibió; no lo decodifique, no construya el suyo propio y no asuma que su formato es estable entre versiones de la API. La única garantía es: pase el token que se le entregó, obtenga la página siguiente.

Ejemplo: paginación a través de sus lotes

Primera solicitud, aún sin 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"
}

Siguiente solicitud, usando el token de la respuesta anterior:

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

Siga repitiendo con el next_page_token de cada respuesta hasta que has_more devuelva false. Un token mal formado o expirado devuelve un error invalid_parameter (consulte Manejo de errores) en lugar de devolver silenciosamente la primera página nuevamente — así que un token corrupto se manifiesta de inmediato en lugar de reiniciar su bucle sin aviso.

El parámetro limit

Cada endpoint de lista acepta un parámetro de consulta limit opcional para controlar el tamaño de página, cada uno con su propio valor predeterminado y máximo (consulte la página del endpoint individual en Referencia de la API para conocer sus límites exactos). Solicitar un limit fuera del rango permitido devuelve invalid_parameter.