Skip to main content
All top-level resources support pagination. All 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 is used whenever a request does not include an offset 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, or null on the last page
  • previous: URL for the previous page, or null on the first page
  • results: The current page of data
To page through a full list, request the first page without a cursor, then request each next URL until next is null.

Ordering

In cursor mode, results are ordered by descending id (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)

Offset-based pagination is deprecated and not recommended. It remains supported so existing integrations keep working, but migrate to cursor-based pagination when you can.
If a request includes an offset parameter, the API uses offset-based pagination with the limit and offset parameters.
  • count: The total number of items in the full result set
  • next: URL for the next page of results
  • previous: URL for the previous page of results
  • results: The current page of data
Offset pagination has two costs:
  • Each page is slower than the last. To return a page, the database reads and discards every row before offset, and it computes the full count on 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 the offset parameter and follow the next URL until it is null. Before (offset, deprecated):
After (cursor, recommended):
Keep these differences in mind when you migrate:
  • Cursor responses have no count. Do not compute page numbers or stop conditions from a total. Loop until next is null.
  • Treat cursor as opaque. Do not parse, build, or modify cursor values. Use the next and previous URLs exactly as returned.
  • Pass filters and order_by on the first request only. The next URL 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, pass order_by explicitly.

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.