Skip to main content
Every list route returns one page:
array
The rows on this page.
string | null
Pass this back as cursor to get the next page. null on the last page.
boolean
true while there are more pages. Loop until it is false.
There is no total row count on a list. Counting every matching row on every request is the expensive part of a list, so the API does not do it. If you need a count, page to the end and count what you received. The one exception is the work items list, whose counts say how many items the whole queue holds in each status.

Parameters

integer
Rows per page. Leave it out for the route’s default. The most a page may hold is listed in Rate limits. Most routes refuse a larger limit with a 400; the engine searches and claims lists use their maximum instead, and a brands report page can hold fewer rows than you ask for (see Reports).
string
The previous page’s next_cursor. Leave it out for the first page.

A cursor belongs to its query

A cursor remembers the filters that produced it. Send it with different parameters (another window, another engine, another limit) and the request is refused with 400, error.field set to cursor, and the message “this cursor was issued for a different set of filters; request the first page again”. That is deliberate: reading on from the wrong place would silently skip rows and hand you a short page that looks complete. So keep every other parameter exactly the same from page to page, change only cursor, and treat the cursor as an opaque string. Do not build one or edit one.

Short pages, and empty ones

A page can hold fewer rows than limit and still be followed by more. On the report routes a page can even be empty with has_more still true, when the days it read held no rows. Never stop because a page was short or empty; stop when has_more is false.

Walking every page

The same loop works for CSV: the next cursor then arrives in a header rather than in the body. See CSV output.

Reports

Date-first pages, and why a report page can be short.

CSV output

Paging a CSV with the Citino-Next-Cursor header.

Rate limits

Page sizes and request budgets.

Errors

What a refused cursor looks like.