# Pagination par curseur — Guide next_page_token

> Les points de terminaison de liste de l'API v1 utilisent une pagination opaque par curseur — pas de numéros de page — via un next_page_token que vous renvoyez textuellement, sans jamais le décoder ni le construire vous-même.

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 :

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

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

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

```bash
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](/developers/guides/errors)) 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](/developers/reference/) pour ses limites exactes). Demander une `limit` en dehors de la plage autorisée renvoie `invalid_parameter`.

---

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