Concepts
Pagination
Every list is cursor-paginated: read data and follow next_cursor until it is null, or let the SDKs iterate for you.
Pages and cursors
Every list operation returns one page:
JSON
{ "data": [ … ], "next_cursor": "c2VjXzAx…" }Pass next_cursor back as cursor to get the following page; the last page has "next_cursor": null. limit sets the page size (1 to 200, default 50 on most lists). Cursors are opaque: do not build or parse them. Stop when next_cursor is null, not when a page looks short.
# Follow `next_cursor` until it is null.
CURSOR=""
PAGE_NO=1
while :; do
PAGE=$(curl -sS --fail-with-body -G "$API_BASE_URL/secrets" -H "$AUTH" \
--data-urlencode "limit=2" ${CURSOR:+--data-urlencode "cursor=$CURSOR"})
echo "page $PAGE_NO: $(echo "$PAGE" | jq -r '[.data[].name] | join(", ")')"
CURSOR=$(echo "$PAGE" | jq -r '.next_cursor // empty')
[ -z "$CURSOR" ] && break
PAGE_NO=$((PAGE_NO + 1))
doneIn the SDKs
List methods return a page you can read directly, and that is also an iterator over every item: it fetches further pages as the loop reaches them.
// Every item, fetching further pages as the loop reaches them:
for await (const secret of client.secrets.list({ limit: 2 })) {
console.log('secret:', secret.name);
}The OpenAI-compatible GET /v1/models on the inference API follows OpenAI's shape instead: it returns every model in one response, with no cursor.