Using Cursor-based Pagination in Our API

Cursor-based pagination is an efficient way to navigate through large datasets. Instead of fetching records based on a page number, we use a "pointer" (or a cursor) that refers to a specific record in the dataset. With this method, you can retrieve records before or after the cursor's position.

How the Cursor Works

The cursor in our API is a base64-encoded string containing:

  1. The ID of the last item from the previous batch (last_id).
  2. The value of the property by which the dataset is sorted (last_value).

To fetch the next page of records, you simply send the cursor value back to the server. The server will then decode the cursor to identify the position of the last item you received and send you the records that come after it.

If no cursor is provided in your request, the API defaults to sending the first set of records.

Making a Request Using a Cursor

  1. Initial Request (without cursor)

    Make a GET request to the endpoint without providing any cursor. This will fetch the first set of items.


    The response will look something like this:

      "items": [ /*... array of items ...*/ ],
      "cursor": {
        "starting_at": "base64_encoded_cursor",
        "previous": null
  2. Fetching the Next Page (using the cursor)

    Extract the starting_at value from the previous response's cursor object and use it to make your next request.


    The subsequent responses will also contain a cursor object with a new starting_at value which you can use for the next page.

  3. Going Back to the Previous Page

    If you wish to go back to a previous page, use the previous value from the cursor object. However, it's important to note that previous is only available if the current cursor isn't the same as the initial request's cursor.

Remember, each time you make a request using a cursor, the response will always include the next cursor so you can seamlessly paginate through the records.


Using cursor-based pagination over traditional page-number based pagination has the following benefits:

By following the steps above, you can easily and efficiently paginate through the large datasets provided by our API using cursor-based pagination.