Cursor-based pagination is a method to paginate large datasets by using a cursor, which serves as a reference point for fetching the next set of results. Unlike offset-based pagination (which uses numeric indexes), cursor-based pagination ensures stable and consistent results, especially for datasets that might change frequently.
Our API uses a cursor parameter to represent the position in the dataset. You’ll pass this cursor to retrieve the next set of results.
Each paginated response includes:
data: The actual results for the current page. Note that the name of this property is not fixed and can be named differently according to the context (e.g.:employees,orders,plannings, ...)cursors: an object containing a cursor which can be used in subsequent calls.next: The cursor for the next page. This cursor is not present when fetching data for the last page.
Example response body:
{
"data": [
...
],
"cursors": {
"next": "bmV4dF9fcGFnZQ"
}
}Older endpoints might still support more than the next cursor. The cursors for their responses will contain:
self: The cursor for this page. This cursor is not present when there are no items returned for the initial GET.prev: The cursor for the previous page. This cursor is not present when fetching data for the first page.next: The cursor for the next page. This cursor is not present when fetching data for the last page.
Example response body:
{
"data": [
...
],
"cursors": {
"self": "c2VsZl9fcGFnZQ",
"prev": "cHJldmlvdXNfX3BhZ2U",
"next": "bmV4dF9fcGFnZQ"
}
}A cursor can be provided in subsequent calls via the cursor request parameter:
GET /items?cursor=bmV4dF9fcGFnZQTo fetch the first page of a collection of items, you don't need to provide any cursor.
GET /itemsTo fetch the next page of results, use the next cursor from the response in your next request.
GET /items?cursor=bmV4dF9fcGFnZQTo navigate back to the previous page, use the prev cursor (if provided).
GET /items?cursor=cHJldmlvdXNfX3BhZ2U