Zum Inhalt springen
Szenera DeveloperHandbuch
API › Grundlagen › Blättern: limit, cursor, items, nextCursor
Kapitel

Blättern: limit, cursor, items, nextCursor

Cursor-Blättern auf allen Listen, die Grenzen 50/200 und 25/100, die vier Routen mit page — und wie die CLI mit --all allen Seiten folgt.

3 Minuten LesezeitAPIStand: 25.10.2026

Auf dieser Seite

Bevor Sie loslegen

Für wen
Wer eine Liste vollständig lesen oder eine Seite in einer Oberfläche zeigen will.
Voraussetzung
ein Schlüssel ak_… mit einem *.list-Recht — im Beispiel scene.list (Klasse Nur Lesen)

Listen der API werden über einen Cursor geblättert: limit begrenzt die Seite, cursor setzt sie fort, die Antwort führt items und — solange weitere Datensätze folgen — nextCursor. Diese Seite nennt die Grenzen, die vier Ausnahmen mit page und die Schleife, die alle Seiten einsammelt.

Cursor-Blättern

Teil Regel
limit (Abfrageparameter) ganze Zahl 1–200, Vorgabe 50
cursor (Abfrageparameter) der Wert von nextCursor der vorigen Seite; beim ersten Aufruf weglassen
items (Antwort) die Datensätze dieser Seite
nextCursor (Antwort) die Marke der nächsten Seite; fehlt auf der letzten Seite
total (Antwort) die Gesamtzahl, wo die Route sie kennt; sonst fehlt das Feld

Der Cursor ist stabil bei Einfügungen: Ein Datensatz, der während des Blätterns dazukommt, verschiebt keine Seite. 29 Operationen der Referenz nehmen cursor, 34 nehmen limit.

curl -sS "$SZENERA_API/v1/scenes?limit=2" \
  -H "Authorization: Bearer $SZENERA_API_KEY"

Die Antwort, je Szene auf vier Felder gekürzt:

{
  "items": [
    { "id": "scn_01KJPX8NH0SZENE00000000001", "name": "Notdienst & Wetter", "status": "published", "version": 4 },
    { "id": "scn_01KJPX8NH0SZENE00000000002", "name": "Wochenkarte", "status": "draft", "version": 1 }
  ],
  "nextCursor": "c2NuOjIwMjYtMDctMDY"
}

Gefilterte Listen: 25 und 100

Die gefilterten Listen der Verwaltung — Organisationen, Konten, Geräte, Rollen, Erteilungen, Schlüssel — deckeln niedriger, weil jede Zeile mehr trägt: Vorgabe 25, höchstens 100. Ein limit darüber antwortet 422 Validation.Failed. Die Referenz nennt an limit heute keine Grenze; es gelten 200/50 für Cursor-Listen und 100/25 für die gefilterten Listen der Verwaltung (Organisationen, Konten, Geräte, Rollen, Erteilungen, Schlüssel).

Die Ausnahme: page

Vier Listen blättern mit Seitenzahlen statt mit einem Cursor, weil eine Seitenleiste („Seite 3 von 12“) die Gesamtzahl braucht:

Route Inhalt
GET /v1/devices/{id}/commands Befehle eines Geräts
GET /v1/devices/{id}/events Betriebsprotokoll eines Geräts
GET /v1/players/{id}/commands Befehle eines Displays
GET /v1/players/{id}/events Betriebsprotokoll eines Displays
Teil Regel
page ganze Zahl ab 1, Vorgabe 1
limit 1–200, Vorgabe 50
Antwort items, total, page, pageSize — alle vier Pflicht

page und pageSize reisen zurück, obwohl Sie sie geschickt haben: Sie sind die Zahlen, gegen die total gilt.

Kleine Bestände

Kleine, nicht blätterbare Bestände antworten mit einer einfachen Liste ohne items-Hülle. Die Antwortform steht am Endpunkt in der Referenz; ein Client, der auf items prüft, erkennt den Unterschied am Aufbau.

Alle Seiten einsammeln

cursor=""
while :; do
  antwort=$(curl -sS "$SZENERA_API/v1/scenes?limit=200${cursor:+&cursor=$cursor}" \
    -H "Authorization: Bearer $SZENERA_API_KEY")
  echo "$antwort" | jq -c '.items[]'
  cursor=$(echo "$antwort" | jq -r '.nextCursor // empty')
  [ -z "$cursor" ] && break
done

Die Schleife endet, sobald nextCursor fehlt. Prüfen Sie nicht auf einen leeren items-Block als Ende — die letzte Seite kann voll sein.

Kommandozeile

Jeder Listen-Befehl von szenera kennt dieselben drei Flaggen:

Flagge Wirkung
--limit=<anzahl> höchstens so viele Zeilen je Seite; ein Wert außerhalb von 1 bis zum Deckel der Route wird lokal abgewiesen (Exit 1), bevor ein Aufruf hinausgeht
--cursor=<marke> weiterlesen ab dieser Marke; die Kopfzeile eines Ergebnisses nennt sie: „weiter mit --cursor=…“
--all allen Seiten folgen, bis keine mehr kommt; die zusammengehängte Ausgabe trägt kein nextCursor 
szenera scene list --all --json | jq -r '.items[].id'

Wie Sie daraus ein Skript bauen, steht unter Skripte und CI.

Weiterführendes