---
agentTools:
  projectIndex: https://developers.gorgias.com/llms.txt
---

# Cursor-based pagination replaces offset-based pagination for all listing endpoints

#### Changes

[Cursor-based pagination](https://developers.gorgias.com/reference/pagination#offset-based-pagination)  was added to all list resource endpoints. It replaces previous offset-based pagination and provides lower latency when listing resources. This change affects all listing resource endpoints:

* [list customers](https://developers.gorgias.com/reference/get_api-customers)
* [list events](https://developers.gorgias.com/reference/get_api-events)
* [list integrations](https://developers.gorgias.com/reference/get_api-integrations)
* [list jobs](https://developers.gorgias.com/reference/get_api-jobs)
* [list macros](https://developers.gorgias.com/reference/get_api-macros)
* [list rules](https://developers.gorgias.com/reference/get_api-rules)
* [list surveys](https://developers.gorgias.com/reference/get_api-satisfaction-surveys)
* [list users](https://developers.gorgias.com/reference/get_api-users)
* [list tags](https://developers.gorgias.com/reference/get_api-tags)
* [list tickets](https://developers.gorgias.com/reference/get_api-tickets)
* [list views](https://developers.gorgias.com/reference/get_api-views)
* [list widgets](https://developers.gorgias.com/reference/get_api-widgets)

Offset-based pagination is still available, but won't be accessible anymore after 01-08-2022.

### Migration guide

The main difference between offset-based and cursor-based pagination is the parameter used to list resources. Listing resources with offset-based pagination is done with the `page` parameter. Listing resources with cursor-based pagination is done with a `cursor` parameter. The cursor is an **opaque short-lived value** that represents where you are in the list of resources. You don't want to store cursors for a long period of time **as they could expire**.

If you used to use `per_page` to get a specific number of resources, you now need to use `limit`.

#### Example

Let's make an example of cursor-based pagination usage on [list events](https://developers.gorgias.com/reference/get_api-events) endpoint. To fetch your most recent events, you don't have to specify the cursor:

```curl
curl --request GET \
     --url 'https://gorgias.gorgias.com/api/events?limit=2' \
     --header 'Accept: application/json'
```

The server will return the list of events as well as pagination information containing:

* a `prev_cursor` value if there are events before the ones you fetched. It will be `null` if you fetched the events at the beginning of the list (similar to the first page).
* a `next_cursor` value if there are events after the ones you fetched. It will be `null` if you fetched the events at the end of the list (similar to the last page).

```json
{
    "data": [
        {
            "id": 768,
            "context": "be71cef8-ab02-4d89-b33c-1a00c387310d",
            "created_datetime": "2021-11-02T21:58:43.171610+00:00",
            "data": null,
            "object_id": 2,
            "object_type": "User",
            "type": "user-logged-out",
            "user_id": 2,
            "uri": "/api/events/768/"
        },
        {
            "id": 767,
            "context": "a0619320-611d-487b-9f28-5c297fd0793a",
            "created_datetime": "2021-11-02T21:58:32.951424+00:00",
            "data": null,
            "object_id": 1,
            "object_type": "Account",
            "type": "account-updated",
            "user_id": null,
            "uri": "/api/events/767/"
        }
    ],
    "object": "list",
    "uri": "/api/events",
    "meta": {
        "prev_cursor": null,
        "next_cursor": "bmV4dF9fNzY3X18yMDIxLT=="
    }
}
```

To continue to list your events, get older events (default order is most recent events first), you now need to set the `cursor` parameter to the `next_cursor` value returned in the response (`bmV4dF9fNzY3X18yMDIxLT==`)

```curl
curl --request GET \
     --url 'https://gorgias.gorgias.com/api/events?cursor=bmV4dF9fNzY3X18yMDIxLT==&limit=2' \
     --header 'Accept: application/json'
```

The server will return:

```json
{
    "data": [
        {
            "id": 766,
            "context": "60d87c4e-268b-44c3-b453-910d83ed7d2c",
            "created_datetime": "2021-11-01T22:41:55.377130+00:00",
            "data": null,
            "object_id": 2,
            "object_type": "User",
            "type": "user-updated",
            "user_id": 2,
            "uri": "/api/events/766/"
        },
        {
            "id": 765,
            "context": "a7a8534d-4fff-4ddd-aa58-38752ba41d1f",
            "created_datetime": "2021-11-01T10:52:37.921041+00:00",
            "data": null,
            "object_id": 2,
            "object_type": "User",
            "type": "user-logged-in",
            "user_id": 2,
            "uri": "/api/events/765/"
        }
    ],
    "object": "list",
    "uri": "/api/events?limit=2&cursor=bmV4dF9fNzY3X18yMDIxLT==",
    "meta": {
        "prev_cursor": "cHJldl9fNzY2X18yMDIxLTjEzMA==",
        "next_cursor": "bmV4dF9fNzY1X18jM3LjkyMTA0MQ=="
    }
}
```

As you can see, now that you are in the middle of the list, the server returned a value for:

* the previous cursor (`prev_cursor`) to fetch events before the ones you just fetched (newer events)
* the next cursor (`next_cursor`) to fetch events after the ones you just fetched (older events)

Feel free to reach out at **<support@gorgias.com>** if you have any questions.