Cursor Pagination

We will be rolling out an update to one of our API endpoints, the events API, to introduce cursor-based pagination.

We are taking a slow and steady approach of enabling backwards compatibility for a few weeks to transition over and give developers the opportunity to slowly switch.

This means that existing requests won’t suddenly fail; they’ll just stop behaving the way they normally do. We will fully deprecate these fields and you should expect them to no longer work by March 1, 2022.

What changes were made? The /events endpoint will now by default return next and previous cursors, which will be the parameters you should use for the cursor query parameter to the next page in the resulting dataset.

This will lead to significantly faster API response times for you and less intensive APIs for us (and therefore less platform instability!). If you choose to, you will be able to continue using limit, offset, and occurred_after for a period of time in order to not break any existing API calls you might be making now. The occurred_before field will remain to allow you to start your search at a particular point in time.

Eventually, we will deprecate these fields completely. These four fields, which are being used by API users to get the next page of results, will now only be retained for backwards compatibility. The API response for this endpoint will now have two new fields:

{
	"asset_events": [],
	"next:": "cj0xJnA9MjAyMi0wMi0wMiswMiUzQTQ1JTNBMTIuNjQ3MDM2",
	"previous": "cD0yMDIyLTAyLTAyKzAxJTNBNDglM0EzNC4xMzE4Nzk%3D",
}

When users want to get to the next page, they will need to use the next page as the request endpoint.

Why? This update not only simplifies things for users wanting to get to the next page but also leads to much faster response times. Additionally, you will also not be restricted to a smaller result dataset of 10,000 with this change. This is a design limitation of how offset-based queries work, which is not the case with cursor-based pagination.

We are focused on improving operational excellence this will improve the experience for our users, leading to improved performance and reliability.

We plan on eventually rolling cursor pagination to all our list endpoints. You can read more about the advantages of cursor pagination here.