Pagination

Every operation that returns a list pages through it with a cursor.

Parameters

Parameter	Meaning
`limit`	Page size, 1 to 500; default 50. A value outside 1–500 is `422`, field `limit`, code `out_of_range`; it is not cut down to fit
`cursor`	`next_cursor` of the previous page. Leave it out for the first page

The answer is one page:

{
  "items": [],
  "next_cursor": "…"
}

next_cursor is null exactly on the last page. Pass any other value as cursor to get the next page.

The cursor

The cursor is opaque: do not build or change it. A cursor that is damaged or comes from another list is 422, field cursor, code invalid.
The API and MCP use the same cursor strings.

Order and changes between pages

Each page holds the items whose sort key is greater than the cursor, in ascending order (keyset pagination). So rows added between two pages are not repeated, and rows the walk has not reached yet are not skipped. A new row appears on a later page if its key is greater than the cursor.

Each list operation states its order in the reference, for example lists in creation order.

Filters and query parameters

Filters are query parameters; each list operation names its own, for example include_deleted. The query is strict:

Query	Answer
An unknown parameter	`422`, code `unknown_field`
A parameter sent twice	`422`, code `invalid`
A value of the wrong kind, such as `limit=ten`	`422`, code `invalid_type`

Example

A client loop with curl and jq that prints every list of a project:

cursor=""
while :; do
  page=$(curl -s -H "Authorization: Bearer $POSTWIND_KEY" \
    "$POSTWIND_URL/api/v1/projects/$PROJECT_ID/lists?limit=500${cursor:+&cursor=$cursor}")
  echo "$page" | jq -r '.items[].name'
  cursor=$(echo "$page" | jq -r '.next_cursor // empty')
  [ -n "$cursor" ] || break
done

The cursor is base64url, so it needs no escaping in a query string.

MCP

List tools return at most 100 items per call: limit is 1 to 100, default 50. A larger value is validation_failed, field limit, code out_of_range. The cursor argument takes the same strings as the API. See Tool rules.