Core concepts
Pagination
Every list you read answers the same way, and one cursor walks you through it.
The envelope
Every list you read answers the same shape.
{ "object": "list", "data": [ ... ], "has_more": false }data is the page you asked for. has_more tells you whether asking again would return anything.
Asking for the next page
| Parameter | Meaning |
|---|---|
limit | How many, from 1 to 100. Defaults to 25 |
starting_after | The identifier of the last record you saw. Returns the page that follows it |
You page by identifier rather than by page number, so a record created while you're reading doesn't shift what you see.
Keep the last identifier from each page and send it as starting_after on the next, until has_more is false.
Reading events instead
A module's event list takes the same two parameters and adds an exact way to read: pass stream with after set to the last sequence number you handled, and you get everything after it on that stream.
Use that one to catch up. A sequence is per organisation and per stream with no gaps, so you can tell whether you missed something.