Pagination

When listing large data sets through APIs, it needs a mechanism to paginate the list of resources. We support offset pagination or cursor pagination for these "list" APIs. For example, List webhook endpoints, List unsubscribers.

Offset pagination

Most pageable resources support offset pagination.

These APIs share a common structure and accept the following query parameters:

Parameter	Description
page	Page number of the results to be returned, 1-based. Typically, maximum 100.
limit	A limit on the number of results to be returned, or number of results per page, between 1 and 100, defaults to 10.
includeTotal	Return results inside an object that contains the total result count or not. Only use it when you want to fetch a total count, as it takes more time to count.

And return a common JSON structure:

Field	Description
items	An array containing objects returned in this page.
offset	The position of the item this page starts from, zero-based. e.g., the 11th item is at offset 10. This value is calculated by the request parameter `page` and `limit`: `offset = (page - 1) * limit`.
limit	Same as the request parameter `limit`.
length	The actual number of items returned in this page. i.e., `items.length`. It should be less or equal to `limit`.
total	The total number of items (including those that may not be returned in this page). This field is returned only when the request parameter `includeTotal` is set to `true`.

Note

Commonly, these APIs have a maximum of 100 for both page and limit, which means you could only query the first 10,000 items.

Cursor pagination

There are cases that you need to iterate over all the data sets. If possible, we provide cursor pagination for these resources.

Query parameters:

Parameter	Description
limit	A limit on the number of results to be returned, or number of results per page, between 1 and 100, defaults to 10.
pageAfter	A cursor to fetch the next page in cursor pagination. For example, if you make a list request, receive 100 objects and `cursor.after=id:foo`, your subsequent call can include `pageAfter=id:foo` in order to fetch the next page of the list.

Response:

Field	Description
items	An array containing objects returned in this page.
limit	Same as the request parameter `limit`.
length	The actual number of items returned in this page. i.e., `items.length`. It should be less or equal to `limit`.
cursor	A cursor object. Returned only if the endpoint you requested supports cursor pagination.
cursor.after	A cursor to fetch the next page in cursor pagination. For example, if you make a list request, receive 100 objects and `cursor.after=id:foo`, your subsequent call can include `pageAfter=id:foo` in order to fetch the next page of the list. This field is returned only if there are more items in the list. Clients should not store or modify the cursor on their side.

Note

If the response length is 0, or cursor.after is not returned, it means that there are no more items or pages.
Refer to the API Reference to see if they support cursor pagination.