Platform
List endpoint pagination
Read large collections in bounded pages without losing your place. Each surface documents its own limit, offset, filters, and response envelope; SCIM uses its standard one-based pagination model.
On this page
Start here
Use pagination to process a large collection predictably without loading the whole workspace into memory. The platform has several list shapes, so the reliable approach is to follow the contract for the endpoint you call rather than applying one global page abstraction.
Before you begin
- A credential with the read scope or operator access required by the list endpoint
- The endpoint's response key and documented limit, offset, or SCIM parameters
- A stable place in your job state to store the next offset, SCIM startIndex, or opaque next_cursor
Put it into practice
-
Choose a bounded page
Start with the endpoint's default or a smaller limit. Respect its individual maximum; list endpoints do not all share the same cap.
-
Read the correct envelope
Extract the named collection such as messages or tasks and use available count or pagination metadata. For SCIM, read Resources and the standard totalResults, startIndex, and itemsPerPage fields.
-
Advance until complete
Increase offset by the number returned, or startIndex by itemsPerPage for SCIM. Cursor-paged endpoints instead return next_cursor: pass it back as cursor and stop when it is null; offset is ignored there and a tampered cursor returns 400 invalid_cursor. Stop on an empty page or when the reported total has been reached, and tolerate new records appearing during a long scan.
Your client visits each requested page within server bounds, retains workspace scoping, and can resume a long-running scan without restarting from the beginning.
01 REST API list endpoints
detailsKeyed array responses
Collection responses use a resource key such as {"messages": [...]} or {"eval_runs": [...]}. Workspace scoping still comes from authentication; pagination parameters never widen tenant scope.
02 Bounded limit/offset endpoints
reference| Endpoint | Parameters | Response metadata |
|---|---|---|
| GET /api/v1/messages | limit: 1-100 (default 50); offset: 0-100000 | messages and count |
| GET /api/v1/tasks | limit: 0-100 (default 50); offset: 0-10000 | tasks, count, and pagination |
| GET /api/v1/operator/eval_runs | limit: 0-100 (default 50); offset: 0-10000 | eval_runs and pagination |
| GET /api/v1/operator/agent_commands | limit: 1-100 (default 25) | agent_commands |
| GET /api/v1/operator/webhook_subscriptions/:id/deliveries | limit: default 30, max 100 | deliveries |
| GET /api/v1/operator/data_requests | limit: default 50, max 200 | data_requests |
| GET /api/v1/operator/scim_events | limit: default 50, max 200 | scim_sync_events |
| GET /api/v1/operator/observability/search | limit: default 20, max 50 | search hits |
| GET /api/v1/operator/cohorts and GET /api/v1/operator/cohorts/:id members | limit: default 100, max 500 | cohorts / members |
| GET /api/v1/operator/batch_operations | limit: default 25, max 100 | batch_operations |
| GET /api/v1/operator/batch_operations/:id targets | target_limit: default 100, max 500 | targets on the show payload |
03 Cursor-paged endpoints
reference| Endpoint | Parameters | Response metadata |
|---|---|---|
| GET /api/v1/operator/robots | limit: default 25, max 100; signed workspace/filter-bound cursor | robots, next_cursor, previous_cursor; name/id order can move when names change |
| GET /api/v1/operator/robots/:id/locations and /api/v1/robots/me/locations | limit: default 25, max 100; signed workspace/robot-bound cursor | samples, next_cursor, current and geofence_states |
| GET /api/v1/operator/maintenance-work-orders | limit: default 25, max 100; cursor | work_orders and next_cursor; /:id/events is a bounded recent-detail list with archived_audit_url |
| GET /api/v1/operator/service_agents | limit: default 100, max 500; cursor | service_agents and next_cursor |
| GET /api/v1/operator/alerts | limit: default 100, max 500; cursor | alerts and next_cursor |
| GET /api/v1/operator/security/violations | limit: default 50, max 200; cursor | violations and next_cursor |
| GET /api/v1/operator/eval_reviews | limit: default 100, max 500; cursor | eval_review_tasks and next_cursor |
| GET /api/v1/operator/audit_events | limit; cursor | audit_events and next_cursor |
| GET /api/v1/operator/approval_requests | limit; cursor | approval_requests and next_cursor |
| GET /api/v1/traces/:trace_id/events and the operator equivalent | limit: default 100, max 500; cursor | trace_events and next_cursor |
04 Operator list filters
detailsFlat or nested, nested wins
Controllers that use FilterParams.extract accept both ?status=online and ?filter[status]=online. When both are present the nested filter value wins. Invalid values return HTTP 400 with detail such as invalid_status or invalid_kind — not a 422 extra.errors map. Some lists (eval runs, traces, approvals, security violations, OTA updates) only read the nested filter map; a top-level ?status= is ignored there. GET /api/v1/operator/ota-updates accepts filter[status], filter[update_type], and filter[robot_id] only.
05 SCIM 2.0 pagination
detailsParameters
startIndex (1-based, default 1) and count (max results per page, default 50, hard cap 100). filter takes a single eq comparison: Users on userName, emails, emails.value, externalId, or id; Groups on displayName, externalId, or id. Any other filter is 400 invalidFilter.
Response envelope
Returns schemas, totalResults, startIndex, itemsPerPage, and Resources array following the SCIM 2.0 ListResponse standard. itemsPerPage is never more than 100 even if count is larger.
06 SCIM list response example
example{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults": 42,
"startIndex": 1,
"itemsPerPage": 1,
"Resources": [
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"userName": "user@example.com",
"active": true
}
]
}Troubleshooting
- A filter appears to do nothing
- Check whether that endpoint expects filter[name] rather than a top-level parameter. For controllers accepting both, the nested value wins.
- The server returns 400
- Verify numeric bounds and allowed enum values. Invalid operator filters are request errors, not field-validation documents.