Pagination

Offset pagination is unstable while data is changing underneath it. If a new chatbot is created while you are on page 1, everything shifts down and page 2 repeats a row you already saw. Delete one and a row is skipped entirely.

A cursor points at a position in the ordering, not a count of rows before it. Inserts and deletes elsewhere in the list cannot shift it, so a long export neither duplicates nor skips.

Pass the next_cursor you were given as starting_after:

Stop when has_more is false.

Pass previous_cursor as ending_before to step back a page. That is what powers a "previous" button.

Send one or the other, never both.

limit defaults to 20 and is clamped by the server, so asking for 10,000 gets you the maximum rather than an error.

List endpoints accept a created range, in Unix seconds or ISO-8601:

• created[gte] — at or after.
• created[lte] — at or before.

Combine with cursors to export a month without holding the whole thing in memory.

sort accepts id or created_at, newest first by default. Prefix with + for ascending:

An unrecognised sort field falls back to id rather than erroring.

• Looking for page or offset. Neither exists.
• Building your own cursor. They are opaque; treat them as strings and pass them back unmodified.
• Ignoring has_more. An empty data array with has_more: true is possible when a filter excludes a whole page.
• Fetching one row at a time. The fastest way to hit a rate limit.

• Rate limits — budgeting a large read.
• Errors — what a bad cursor returns.
• Conversations — the endpoint most often exported.