SDKs
Pagination
A list endpoint that returns one page is a list endpoint every caller writes a loop around. Configure pagination on the endpoint and the generator writes the loop for them.
Select an endpoint in SDK Studio and open its pagination settings.
The settings
| Setting | What it does | Example |
|---|---|---|
| Pagination strategy | How the next page is requested | Cursor |
| Items field | The response field holding the page's items | data |
| Next field | The field that advances the page | next_cursor |
| Auto-paginate helper | Emit an iterator that fetches pages for the caller | On |
Strategies
What callers get
With Auto-paginate helper on, the method hands back an iterator that fetches pages as they're consumed.
for await (const user of client.users.list({ limit: 100 })) {
console.log(user.id);
}The caller never sees a cursor. Each page is fetched only when they reach it, so an early break costs one request.
With it off, the method returns a single page and the caller writes the loop themselves, which is the thing you were trying to save them.
Getting the fields right
Items field and Next field name fields in the response body, not parameters.
Nothing validates these against a real response. If Items field names something the response doesn't have, the SDK builds and publishes cleanly, then returns nothing at runtime. Check them against an actual response before you publish.
For a response shaped like this:
{
"data": [{ "id": "usr_1" }, { "id": "usr_2" }],
"next_cursor": "eyJvIjoyfQ",
"has_more": true
}Set Items field to data and Next field to next_cursor.
Endpoints without pagination
Leave it off. An endpoint returning a bounded list doesn't need an iterator, and adding one implies the list might be long.