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 passingnext_cursor as starting_after until has_more is false:
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 ownsort 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.
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’sprevious_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 aprevious_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:
- Fetch the first page and store its
previous_cursor. - Later, request the list with
ending_beforeset to the stored cursor. - If
datais empty, nothing is new. Keep the cursor you have: an empty page has both cursorsnull. - Otherwise process the items and store the page’s
previous_cursorin place of the one you had. - If
has_moreistrue, request the list again with the new cursor, and repeat until it isfalse.
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.