Skip to main content
Endpoints that support pagination use cursor-based pagination: there are no page numbers or offsets. You request a first page with a limit, and each response hands you an opaque next_token to fetch the following page. Each endpoint declares whether it supports pagination on its API Reference page. Like every tipee API call, the examples below are POST requests with a JSON body (see First steps).

​
Requesting a page

Pagination is controlled by the pagination object of the request body:
Both fields are part of the pagination object: send them explicitly, with null as the value where you have none.
Always set an explicit limit — fetching an entire collection in a single call can be slow on large datasets and counts against your rate limits.

​
Response envelope

Paginated endpoints wrap their results in an envelope:
data contains up to limit entries. next_token is the cursor for the next page, or null when there is no further page. Some endpoints can also return the total size of the collection. For example, /api/directory/resources.list adds total_count and total_count_approximate to the envelope when the request sets "with_total_count": true; its counting_mode property (strict or approximate) trades accuracy for speed.
.list endpoints that do not declare pagination return a plain JSON array, without an envelope.

​
Iterating through pages

1

Fetch the first page

Send your request with "next_token": null and an explicit limit, along with your filters and orders.
2

Follow the cursor

Process data, then resend the exact same request with next_token set to the value from the response.
3

Stop at the end

Stop when the response contains "next_token": null or an empty data array.
You must resend identical filters and orders with each next_token — changing them invalidates the cursor and the API responds with 422 Invalid next_token.
A few rules to keep your iteration reliable:
  • Treat next_token as an opaque string: never build, decode, or modify it.
  • Send explicit orders whenever possible: the cursor is derived from the sorted values, so a deterministic order guarantees stable pages (see Order).
  • Check both stop conditions: when the collection size is an exact multiple of limit, the last full page still carries a non-null next_token and the following page comes back empty.

​
Full example

First page — resources of a kind, filtered and sorted, with a total count:
Second page — the same request, with the token swapped in:

​
Common errors

The response body contains a message describing the problem — see Error Handling for the general error format.