Cursor-Based Pagination

What is Cursor-Based Pagination?

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.

How It Works in Our API

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.

Response format

Each paginated response includes:

1. items : The actual results for the current page. Note that the name of this property is not fixed and can be named differently according the context (e.g.: employees , orders , plannings , ...)
2. cursor : an object containing cursors which can be used in subsequent calls.
   1. self : The cursor for this page. This cursor is not present when there are no items returned for the initial GET.
   2. prev : The cursor for the previous page. This cursor is not present when fetching data for the first page.
   3. next : The cursor for the next page. This cursor is not present when fetching data for the last page.

Example response body:

{
  "items": [
    ...
  ],
  "cursor": {
    "self": "c2VsZl9fcGFnZQ",
    "prev": "cHJldmlvdXNfX3BhZ2U",
    "next": "bmV4dF9fcGFnZQ"
  }
}

Passing the cursor

Cursors can be provided in subsequent calls via the cursor request parameter:

GET /items?cursor=bmV4dF9fcGFnZQ

Examples

Fetching the first page

To fetch the first page of a collection of items, you don't need to provide any cursor.

GET /items

Fetching the Next Page

To fetch the next page of results, use the next cursor from the response in your next request.

GET /items?cursor=bmV4dF9fcGFnZQ

Fetching the Previous Page

To navigate back to the previous page, use the prev cursor (if provided).

GET /items?cursor=cHJldmlvdXNfX3BhZ2U