Pagination
Cursor-based pagination for list operations, page size limits, and how to walk a full list.
List operations return one page at a time. Each page carries an opaque nextCursor. Pass it back as cursor to get the next page, and stop when a page comes back without one.
Request and response
| Where | Field | Rule |
|---|---|---|
| Query | cursor | The nextCursor from the previous page. Omit it for the first page. |
| Query | limit | The maximum number of items on the page. An integer from 1 to the operation's maximum. |
| Response | nextCursor | The cursor for the next page. It is absent or null on the last page. |
Most list responses put their items in an items array. Some runtime lists name the array after the resource instead, for example runs, threads, messages, approvals, webhooks, deliveries, or schedules. Each operation's reference page shows its response schema.
Search operations that take a JSON body, such as searching runs or agent email messages, put cursor and limit in the body instead of the query string.
Page size limits
Most lists accept a limit from 1 to 100. Some operations allow a different maximum.
| Operations | Maximum limit |
|---|---|
| Most list operations | 100 |
| Usage, cost, and spend records, and API key usage | 1000 |
| Memory spaces, memory policies, memory space grants, and memory review items | 200 |
| Run runtime logs | 500 |
| Budget periods | 24 |
| Memories | 20 |
When you omit limit, the operation picks its own default page size. Each reference page lists the exact range.
Cursors are opaque and scoped
Treat a cursor as an opaque string. Do not parse it, build it, or store it for later use in a different context.
- Most cursors are 1 to 4096 characters. Evaluation list cursors can be up to 8192 characters.
- A cursor is bound to the scope that produced it. Using it with a different organization, project, or environment fails with status 400 and code
invalid_cursor. - A malformed or modified cursor also fails with
invalid_cursor.
Send the same tenant headers and filters on every page of a walk.
Walk a full list
List commands take --page-size and --cursor. With --json, the output includes nextCursor:
deployments project list --page-size 50 --json
deployments project list --page-size 50 --cursor "$NEXT_CURSOR" --json--page-size accepts only a whole number. Tenancy list commands accept 1 to 100. Other list commands accept 1 to 200 unless the command sets its own maximum, and the API still applies the operation's limit.