Find methods return a page of results along with links to the next and previous pages. Each page returns up to 100 results, controlled with the limit parameter.
Use cursor-based pagination. It is the default, and it is the only method we recommend. Offset-based pagination is still supported for existing integrations, but it is deprecated and not recommended for new or updated code.
Cursor-based pagination (recommended)
Cursor-based pagination is used whenever a request does not include anoffset parameter. Cursor pagination gives you two guarantees that offset pagination cannot:
- Consistent speed at any depth. Every page returns in about the same time, whether it is the first page or the ten-thousandth.
- No skipped or repeated records. If records are created or deleted while you page through a list, you do not miss records or see the same record twice.
next: URL for the next page of results, ornullon the last pageprevious: URL for the previous page, ornullon the first pageresults: The current page of data
cursor, then request each next URL until next is null.
Ordering
In cursor mode, results are ordered by descendingid (newest records first) unless the endpoint defines its own default ordering. To choose a different order, pass order_by on the first request. The next and previous URLs keep that ordering.
Offset-based pagination (deprecated)
If a request includes anoffset parameter, the API uses offset-based pagination with the limit and offset parameters.
count: The total number of items in the full result setnext: URL for the next page of resultsprevious: URL for the previous page of resultsresults: The current page of data
- Each page is slower than the last. To return a page, the database reads and discards every row before
offset, and it computes the fullcounton every request. Deep pages of large lists get progressively slower and are more likely to time out. - Records can be skipped or repeated. If records are created or deleted while you page through a list, the rows shift between requests. A record can move past your offset and be skipped, or move back and be returned twice.
Migrating from offset to cursor
Drop theoffset parameter and follow the next URL until it is null.
Before (offset, deprecated):
- Cursor responses have no
count. Do not compute page numbers or stop conditions from a total. Loop untilnextisnull. - Treat
cursoras opaque. Do not parse, build, or modify cursor values. Use thenextandpreviousURLs exactly as returned. - Pass filters and
order_byon the first request only. ThenextURL carries them forward. - Expect a different default order. Offset mode keeps each endpoint’s existing order, while cursor mode defaults to descending
id. If your code depends on order, passorder_byexplicitly.
Summary: Use cursor-based pagination. Follow
next until it is null, treat cursors as opaque, and do not rely on count. Offset-based pagination is deprecated and is supported only for existing integrations.