Pagination

Some endpoints use pagination in order to improve server responsiveness.  This means that your application will receive a subset (or "page") of data at a time, and can make another request to receive the next page.  There are two forms of pagination that our APIs use: limit-offset and cursor-based.

Limit Offset Pagination

With limit-offset pagination, your application will include a "limit" parameter, which limits the amount of data the server sends in a single response.  For example, with a limit value of100, the API will respond with100 results at a time.  Many APIs will have a maximum value for "limit".

Each set of results is called a page.  Pages are 1-indexed, and your application will indicate which page of data it wants.  (i.e., the first 100 results are on the first page, the second 100 results are on the second page, and so forth).  The server will indicate when there are no more pages remaining.  The mechanism for indicating no more pages will vary across APIs, and will be found in our API reference.  (e.g., sometimes the indication is in a header value, sometimes it will be in the response body itself).

Cursor Pagination

Cursor pagination is the preferred approach for reading entire data sets, as it is more performant than limit-offset pagination.

With cursor pagination, your application will still include a "limit" parameter, which limits the amount of data on a particular page.  The server will respond with an opaquenext_cursor string alongside the results.  To retrieve the next page of results, simply send the value ofnext_cursor back to the API on the next request.  (The first request will not have a cursor).  The API uses this value to calculate the next page of results.  Whennext_cursor is empty, you've reached the end of the results.