Pagination
Certain API list endpoints return lists of objects. For example, the GET /users endpoint returns
a list of User objects. When the number of objects in the list is large, the API will paginate the
results.
All of our APIs provide iterator methods that will automatically paginate through lists that span more than one page of results. Check the documentation for your preferred SDK for additional information.
When using the API directly, there are two GET parameters that control pagination on list requests:
| Parameter | Description |
|---|---|
| cursor string | Cursor representing a point from a previous list request to resume from on this request. |
| per_page integer | Number of records to show per page. Default: 1,000. Max: 10,000. 1,000 or less is recommended. |
List requests that have another page of records available will return the HTTP header
X-Files-Cursor-Next. This header will contain a value to be used as the cursor parameter when
you load the next page of the list.
If a cursor was provided to access the page, the API will also return X-Files-Cursor-Prev which is
a cursor that can be used to navigate to the previous page of results.
When using a cursor, you must keep the per_page value (number of records per page) consistent
between pages.
Extracting Information from the Cursor
The cursor is a string which consists of a page number prefix and an encrypted cursor part separated
by a colon (:).
Example: PAGE_NUMBER:encrypted_cursor_part. You can use the page number to show a page number in a
UI, if applicable.