Guide

Pagination

Chaque point de terminaison de liste en v1 (GET /batches, GET /account/usage et tout futur point de terminaison de liste) est paginé de la même manière : un curseur, pas un numéro de page.

L'enveloppe de liste

Chaque réponse de liste possède les trois mêmes champs de premier niveau :

{
  "data": [ /* ... */ ],
  "has_more": true,
  "next_page_token": "eyJpZCI6IDQyfQ"
}
  • data — le tableau des résultats pour cette page.
  • has_more — indique si une autre page existe après celle-ci.
  • next_page_token — renvoyez-le tel quel avec ?page_token= dans votre prochaine requête pour obtenir la page suivante. Toujours null quand has_more est false — les deux champs ne sont jamais en désaccord.

Pourquoi un curseur et pas un décalage

Il n'existe pas de pagination de type ?page=2 dans v1, ni de paramètre offset. Des listes comme vos lots ou votre historique d'utilisation changent constamment — de nouveaux lots se terminent, de nouvelles lignes d'utilisation sont écrites — donc une « page 2 » basée sur un décalage peut silencieusement sauter ou répéter des lignes si quelque chose est inséré entre vos requêtes. Un curseur évite cela : chaque jeton pointe vers une position exacte dans l'ordre sous-jacent, pas vers un décalage numérique changeant.

Le jeton est opaque

next_page_token n'est pas un numéro de page, et son encodage interne ne fait pas partie du contrat — traitez-le strictement comme une chaîne opaque. Transmettez-le exactement comme reçu ; ne le décodez pas, n'en construisez pas un vous-même et ne présumez pas que son format est stable d'une version d'API à l'autre. La seule garantie est la suivante : transmettez le jeton qui vous a été donné, obtenez la page suivante.

Exemple : parcourir vos lots

Première requête, pas encore de jeton :

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"
}

Requête suivante, en utilisant le jeton de la réponse précédente :

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

Répétez l'opération avec le next_page_token de chaque réponse jusqu'à ce que has_more renvoie false. Un jeton mal formé ou expiré renvoie une erreur invalid_parameter (voir Gestion des erreurs) plutôt que de renvoyer silencieusement la première page — ainsi, un jeton corrompu est signalé immédiatement au lieu de redémarrer votre boucle en silence.

Le paramètre limit

Chaque point de terminaison de liste accepte un paramètre de requête limit facultatif pour contrôler la taille de la page, chacun ayant sa propre valeur par défaut et son maximum (voir la page du point de terminaison concerné dans la Référence API pour ses limites exactes). Demander une limit en dehors de la plage autorisée renvoie invalid_parameter.

📮 contact email: [email protected]