# Cursor-basierte Paginierung – next_page_token-Leitfaden

> Listen-Endpunkte in der v1-API verwenden eine opake cursor-basierte Paginierung – keine Seitennummern – über einen next_page_token, den Sie unverändert zurückgeben und niemals selbst dekodieren oder konstruieren.

Jeder Listen-Endpunkt in v1 (`GET /batches`, `GET /account/usage` sowie jeder zukünftige Listen-Endpunkt) wird auf die gleiche Weise paginiert: mit einem Cursor, nicht mit einer Seitennummer.

## Der Listen-Envelope

Jede Listenantwort hat dieselben drei Felder auf oberster Ebene:

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

- `data` — das Array der Ergebnisse für diese Seite.
- `has_more` — gibt an, ob nach dieser Seite eine weitere Seite existiert.
- `next_page_token` — übergeben Sie dies als `?page_token=` bei Ihrer nächsten Anfrage, um die nächste Seite zu erhalten. Ist immer `null`, wenn `has_more` `false` ist – die beiden Felder widersprechen sich nie.

## Warum ein Cursor und kein Offset

Es gibt in v1 keine `?page=2`-Paginierung und keinen `offset`-Parameter. Listen wie Ihre Batches oder Ihr Nutzungsverlauf ändern sich ständig – neue Batches werden abgeschlossen, neue Nutzungszeilen werden geschrieben – daher kann eine offset-basierte „Seite 2“ stillschweigend Zeilen überspringen oder wiederholen, wenn zwischen Ihren Anfragen etwas eingefügt wird. Ein Cursor vermeidet dies: Jeder Token zeigt auf eine exakte Position in der zugrunde liegenden Reihenfolge, nicht auf einen sich verschiebenden numerischen Offset.

## Der Token ist opak

`next_page_token` ist keine Seitenzahl, und seine interne Kodierung ist nicht Teil des Vertrags – behandeln Sie ihn strikt als opaken String. Geben Sie ihn genau so zurück, wie Sie ihn erhalten haben; dekodieren Sie ihn nicht, konstruieren Sie keinen eigenen und gehen Sie nicht davon aus, dass sein Format über API-Versionen hinweg stabil ist. Die einzige Garantie ist: Übergeben Sie den Token, den Sie erhalten haben, und Sie bekommen die nächste Seite.

## Beispiel: Durch Ihre Batches blättern

Erste Anfrage, noch kein 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"
}
```

Nächste Anfrage mit dem Token aus der vorherigen Antwort:

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

Wiederholen Sie dies mit dem `next_page_token` jeder Antwort, bis `has_more` den Wert `false` zurückgibt. Ein fehlerhafter oder abgelaufener Token gibt einen `invalid_parameter`-Fehler zurück (siehe [Fehlerbehandlung](/developers/guides/errors)), anstatt stillschweigend die erste Seite erneut auszuliefern – ein verstümmelter Token wird also sofort sichtbar, anstatt Ihre Schleife unbemerkt neu zu starten.

## Der Parameter `limit`

Jeder Listen-Endpunkt akzeptiert einen optionalen `limit`-Query-Parameter zur Steuerung der Seitengröße, jeweils mit eigenem Standardwert und Maximum (siehe die Seite des jeweiligen Endpunkts in der [API-Referenz](/developers/reference/) für die genauen Grenzen). Die Angabe eines `limit` außerhalb des zulässigen Bereichs gibt `invalid_parameter` zurück.

---

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