Skip to main content
Every endpoint that returns a list is paginated the same way, with cursors. There are no page numbers and no offsets.

The List Object

Parameters

Send starting_after or ending_before, never both. Without either, you get the first page.

Read a Whole List

Fetch the first page, then keep passing next_cursor as starting_after until has_more is false:
Stop when has_more is false. Do not work it out from the number of items on a page or from the cursors: the last page still has a next_cursor.

Order

A list is sorted newest first unless the endpoint says otherwise. An endpoint that lets you choose the order documents its own sort parameter. New items do not shift the pages. A cursor marks a position in the list, not a count of items to skip. If items are created while you are paging, the next page still starts right after the last item you saw: nothing is repeated and nothing is skipped.

Cursors

  • A cursor is opaque. Do not parse it, build it or change it. Store it as a string of up to 512 characters.
  • A cursor belongs to the request that returned it. Use it with the same endpoint, the same filters and the same sort. To change a filter or the sort, start again from the first page.
  • A cursor works only with a key of the account it was issued to.
A cursor that was not issued by this list for this request (one that was changed, or that came from another list, another account, another set of filters or another sort) is answered with 400 and the code cursor_invalid:
param is starting_after or ending_before, whichever held the cursor. Handle cursor_invalid by starting the list again without a cursor: the same cursor will not work on a retry. A cursor can also stop being valid over time, so do not rely on one you stored long ago. The other pagination mistakes are answered with 400 and parameter_invalid, with param naming the parameter: sending both starting_after and ending_before, a cursor that is empty or longer than 512 characters, and a limit outside 1 to 100. See Errors.

Page Backwards

Pass a page’s previous_cursor as ending_before to get the items before it. The items on that page are in the list’s usual order, and has_more says whether more items lie further back.

Check for New Items

Both cursors are set on every page that has items. So the first page of a newest-first list has a previous_cursor, even though nothing is before it yet. Keep that cursor and pass it as ending_before later to fetch only the items created since:
  1. Fetch the first page and store its previous_cursor.
  2. Later, request the list with ending_before set to the stored cursor.
  3. If data is empty, nothing is new. Keep the cursor you have: an empty page has both cursors null.
  4. Otherwise process the items and store the page’s previous_cursor in place of the one you had.
  5. If has_more is true, request the list again with the new cursor, and repeat until it is false.
A stored cursor does not last for ever. If a request with it is answered with cursor_invalid, read the list from the first page again and store the new previous_cursor. Make sure processing an item twice is harmless, for example by keeping the IDs you have already handled.

Summary of the Cursor Fields