Paginierung

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:

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

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

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

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), 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 für die genauen Grenzen). Die Angabe eines limit außerhalb des zulässigen Bereichs gibt invalid_parameter zurück.