Agent evidence pagination

Use cursor and limit to page through agent evidence. A cursor is opaque: use the continuation returned by that endpoint, preserve its value, and URL-encode it as one query parameter.

Lists covered by this contract

The single-cursor rule applies to these REST lists:

GET /api/v1/fleet
GET /api/v1/agent-events
GET /api/v1/action-receipts
GET /api/v1/agent-sessions
GET /api/v1/agent-turns
GET /api/v1/assets
GET /api/v1/assets/{assetId}/versions
GET /api/v1/memory-item-labels
GET /api/v1/authority-edges
GET /api/v1/review-signals

The agent run list also requires at most one cursor. An endpoint's required project and evidence selectors still apply on every page.

Request the first or next page

Omit cursor, or send it once with an empty value, to start the first page. For a continuation, send exactly one non-empty cursor. Do not append a new cursor to a URL that already has one; replace the existing value instead.

For example, this request is invalid even when first and second are individually valid cursors:

GET /api/v1/agent-events?project_id=your-project&run_id=your-run&cursor=first&cursor=second

It returns HTTP 400 before the evidence query runs:

{"error":"invalid_request","message":"cursor must be provided at most once"}

Identical duplicates, two empty values, and an empty value followed by a continuation are also rejected. The API does not pick a first or last value and does not silently restart at page one.

A single non-empty value is passed unchanged to the endpoint's cursor validation. Being supplied once does not make an expired, malformed, or otherwise invalid cursor acceptable to that endpoint. Keep the same project, selectors, filters, and explicit time bounds when continuing a list. Paging is not a promise of a frozen snapshot: evidence can still arrive or be removed between requests.

Encode values and limits correctly

Malformed URL query syntax is rejected rather than partially interpreted. Use a URL query builder so characters within a cursor, such as +, &, and ;, are encoded as %2B, %26, and %3B. An encoded & inside one cursor is part of its value, not a second parameter.

limit is optional and may appear at most once. When supplied, it must be a non-empty unsigned 32-bit integer. Omission preserves the endpoint's default; explicit 0 preserves that endpoint's zero-limit behavior. Each endpoint still applies its own page-size default and maximum.

This rule does not prohibit repeated filters. Parameters documented as repeated or comma-separated filters keep that behavior. See the REST API reference for the selectors and filters supported by each list.

Other collection lists

The same duplicate-cursor and malformed-URL refusals also apply to bounded collection lists such as API keys (/api/v1/account/api-keys), alert silences (/api/v1/alerts/silences), and notification channels (/api/v1/notifications/channels). These query-shape errors are refused before the collection is read, including when a page-size limit would otherwise be defaulted or clamped. Those collections keep their own documented limit behavior and response shape; do not substitute an agent-evidence cursor for a cursor returned by a different list.