Skip to content
Szenera DeveloperDocs
API › Basics › Paging: limit, cursor, items, nextCursor
Chapters

Paging: limit, cursor, items, nextCursor

Cursor paging on all lists, the limits 50/200 and 25/100, the four routes with page, and how the CLI follows all pages with --all.

3 minute readAPIUpdated: 10/25/2026

On this page

Before you start

For
Anyone who wants to read a list completely or show a page in a user interface.
Prerequisite
an ak_… key with a *.list permission, in the example scene.list (class Read only)

Lists in the API are paged with a cursor: limit bounds the page, cursor continues it, and the response carries items and, as long as more records follow, nextCursor. This page lists the limits, the four exceptions with page, and the loop that collects all pages.

Cursor paging

Part Rule
limit (query parameter) integer 1–200, default 50
cursor (query parameter) the value of nextCursor from the previous page. Omit it on the first call
items (response) the records of this page
nextCursor (response) the marker of the next page. Missing on the last page
total (response) the total count where the route knows it. Otherwise the field is missing

The cursor is stable under insertions: A record that is added while you page does not shift any page. 29 operations of the reference take cursor, 34 take limit.

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

The response, with each scene trimmed to four fields:

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

Filtered lists: 25 and 100

The filtered administration lists (organizations, accounts, devices, roles, grants, keys) cap lower because every row carries more: default 25, at most 100. A limit above that answers 422 Validation.Failed. The reference currently names no bound on limit. The limits that apply are 200/50 for cursor lists and 100/25 for the filtered administration lists (organizations, accounts, devices, roles, grants, keys).

The exception: page

Four lists page with page numbers instead of a cursor, because a pagination bar (“Page 3 of 12”) needs the total count:

Route Content
GET /v1/devices/{id}/commands commands of a device
GET /v1/devices/{id}/events operations log of a device
GET /v1/players/{id}/commands commands of a display
GET /v1/players/{id}/events operations log of a display
Part Rule
page integer from 1, default 1
limit 1–200, default 50
Response items, total, page, pageSize, all four required

page and pageSize come back in the response even though you sent them: They are the numbers that total refers to.

Small collections

Small collections that cannot be paged answer with a plain list without an items envelope. The response shape is stated at the endpoint in the reference. A client that checks for items recognizes the difference by the structure.

Collect all pages

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

The loop ends as soon as nextCursor is missing. Do not treat an empty items block as the end, because the last page can be full.

Command line

Every list command of szenera knows the same three flags:

Flag Effect
--limit=<count> at most this many rows per page. A value outside the range from 1 to the cap of the route is rejected locally (exit 1) before a call goes out
--cursor=<marker> continue reading from this marker. The header line of a result names it: “weiter mit --cursor=…” (continue with)
--all follow all pages until no more come. The concatenated output carries no nextCursor 
szenera scene list --all --json | jq -r '.items[].id'

How to build a script from this is described under Scripts and CI.