# 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:

- `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:


```json
{
  "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:


```json
{
  "data": [
    ...
  ],
  "cursors": {
    "self": "c2VsZl9fcGFnZQ",
    "prev": "cHJldmlvdXNfX3BhZ2U",
    "next": "bmV4dF9fcGFnZQ"
  }
}
```

### Passing the cursor

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


```http
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.


```http
GET /items
```

##### Fetching the Next Page

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


```http
GET /items?cursor=bmV4dF9fcGFnZQ
```

##### Fetching the Previous Page

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


```http
GET /items?cursor=cHJldmlvdXNfX3BhZ2U
```