> ## Documentation Index
> Fetch the complete documentation index at: https://docs.burthq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> Walk grouped analytics results with signed cursors

Grouped queries can use opaque, signed keyset cursors. A cursor is bound to the
organization, catalog version, selected model members, filters, range, and
ordering, including the requested `limit`. Array ordering is significant,
including selected members, filters, and `in` values. Treat a cursor as an
opaque string: do not decode, edit, or construct one.

The rules are identical for `agent_runs` and `agent_user_activity`; each walk
freezes rows against that model's declared event clock.

Only grouped queries ordered by dimensions paginate. A grouped query that sends
no explicit `order` paginates too: the engine orders by every selected dimension
ascending by default. When `order` is given, each of its terms must be a
dimension for the query to paginate. Totals never paginate. Metric-ordered
grouped queries are single-page top-N results and return `cursor: null`.
Supplying a cursor to a totals query, or ordering by a metric while continuing a
cursor walk, returns `invalid_query`.

## Inclusion boundary and live measures

The first response contains an `asOf` instant. Send the same query fields with
the returned cursor to continue the walk. `asOf` freezes which rows are
included across every page, while measures remain live. A group whose rows
change during a walk can therefore have a changed measure even though the set
of included groups is stable.

## Cursor invalidation

A cursor returns `invalid_cursor` when it is malformed, tampered with, replayed
for another organization or query, or no longer matches the catalog version.
Start a fresh query when this happens.

## Two-page walk

The first request can use a small limit:

```json theme={null}
{
  "model": "agent_runs",
  "metrics": ["run_count"],
  "dimensions": ["user_identifier"],
  "order": [{ "member": "user_identifier", "direction": "asc" }],
  "limit": 2,
  "range": { "start": "2026-08-01", "end": "2026-08-14", "timezone": "UTC" }
}
```

The first page contains the first two dimension groups and a non-null
`cursor`. Send the same JSON with `"cursor": "<cursor from page one>"`.
The second page preserves the original `asOf`; continue until `cursor` is
`null`. Do not change dimensions, metrics, filters, range, timezone, order, or
limit between requests.