GetMyBot-Wissensdatenbank

Paginierung

Lange Listen ohne ausgelassene Einträge seitenweise lesen: Seitengröße, offset und Cursor before.

Auf dieser Seite

Lange Listen wie Kunden oder Nachrichten gibt die API in Seiten zurück. Weitere Seiten abzurufen heißt Paginierung. So muss ein Programm nicht die gesamte Historie auf einmal laden.

Fortsetzungen funktionieren entweder über die Zahl bereits gelesener und zu überspringender Einträge (Offset) oder über einen Zeiger auf die letzte gelesene Stelle (Cursor). Das Schema des jeweiligen Endpoints steht in der API-Referenz.

Schema 1: Offset und X-Total-Count

limit setzt die Seitengröße; offset gibt die Zahl zu überspringender Einträge an. limit=50&offset=100 fordert bis zu 50 Einträge nach den ersten 100 an. Die Parameter folgen nach ? in der URL:

curl -H "Authorization: Bearer <PERSÖNLICHER_TOKEN>" \
  "https://ihre-domain/api/bots/BOT_ID/users?limit=50&offset=100"

Die Gesamtzahl steht im Antwortheader X-Total-Count. Erhöhen Sie offset nach jeder Seite um die Zahl tatsächlich empfangener Einträge, solange offset kleiner als X-Total-Count ist. Der Antwortkörper ist ein Array der aktuellen Seite.

Obergrenze für Offset

Offset-Paginierung ist nicht unbegrenzt: offset über 100.000 wird mit 400 abgelehnt, bei jedem Endpoint, der Offset überhaupt unterstützt. Die Antwort empfiehlt engere Filter oder Cursor-Paginierung.

Große Offsets belasten die Datenbank, da übersprungene Zeilen trotzdem verarbeitet werden. Für große Listen eignen sich Filter, Cursor oder Export. Bei mehr als 100.000 Einträgen erreichen Sie das Ende nicht per Offset. Sie können:

  • mit Endpoint-Filtern wie Zeitraum, Kanal oder Status eingrenzen;
  • auf Cursor wechseln, falls unterstützt. Zahlungs- und Sammlungslisten unterstützen beispielsweise beide Schemata;
  • bei Bedarf für den gesamten Bestand den Export des Bereichs statt seitenweiser API-Abfrage nutzen.

Seitengröße hängt vom Endpoint ab

Es gibt keinen einheitlichen Maximalwert für limit: In Listen kommen 200, 500 oder 1000 vor. Den genauen Wert nennt der Endpoint in der Referenz.

Auch bei zu großem limit unterscheiden sich Endpoints:

  • Manche lehnen mit 400 und einer Meldung wie „limit must be at most 500, got 5000“ ab.
  • Andere wählen stillschweigend den Standard (oft 100) und liefern weniger Einträge als angefordert.

Gehen Sie nie davon aus, dass die Seite die angeforderte Größe hat. Zählen Sie das empfangene Array und erhöhen Sie offset genau um diese Zahl. Wer nach 100 empfangenen Elementen um angeforderte 5000 erhöht, überspringt sonst 98 % der Daten ohne Fehlermeldung. Eine leere Seite allein ist ebenfalls kein verlässliches Ende; berücksichtigen Sie X-Total-Count und die tatsächliche Elementzahl zusammen.

Schema 2: Cursor before und has_more

Cursor-Paginierung dient zeitlich sortierten Feeds, etwa Dialognachrichten. Die Anfrage nutzt limit und optional before, eine ID oder Markierung des letzten bereits empfangenen Eintrags:

curl -H "Authorization: Bearer <PERSÖNLICHER_TOKEN>" \
  "https://ihre-domain/api/bots/BOT_ID/users/USER_ID/dialog?limit=50&before=CURSOR"

Die Antwort enthält eine Seite und has_more. Solange has_more true ist, senden Sie die nächste Anfrage mit dem Cursor des letzten Elements als before. Bei false ist die letzte Seite erreicht.

Welches Schema verwenden?

Der Endpoint legt das Schema fest, nicht der Client. Nachschlagelisten verwenden oft Offset und X-Total-Count, zeitlich geordnete Feeds before und has_more. Prüfen Sie die Endpoint-Referenz.

Weiterführende Artikel