# Blättern: limit, cursor, items, nextCursor

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.

> **Typ:** nachschlagen
> **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**)

## 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`.

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

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

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

```bash
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` |

```bash
szenera scene list --all --json | jq -r '.items[].id'
```

Wie Sie daraus ein Skript bauen, steht unter [Skripte und CI](/de/cli/scripts-and-ci).

## Weiterführendes

- [Was eine Antwort enthält](/de/getting-started/response-contents)
- [Skripte und CI](/de/cli/scripts-and-ci)