The window's END USERS as a ranked register: who your agents served.
The end user is the person on the other side of the agent — the `user.id`
your SDK stamps — not a console login and not an org member. The words are
worth keeping straight: an ORG is the Rius customer, a WORKSPACE is one of
their own clients, and an end user is that client's user.
Read a `user_id` off this register and pass it to `user_activity_summary`
for that person's KPIs, or to `list_agent_traces(user_id=...)` for their
runs. This is the same read the console's Users page makes.
TOP-N by design, not by accident: a B2C workspace can hold millions of end
users, so the server ranks and caps. When it reports more, `q` reaches PAST
the cap by exact id — it is an equality probe, never a substring search, so
a fragment finds nothing rather than scanning millions of ids.
Three figures that are easy to misread, so each travels with its caveat:
anonymous traffic is always reported and is a real subject rather than an
error case; coverage is counted in TRACES because one trace can belong to
two end users under the any-span rule; and a null cost means nothing in the
window was priced, which is not the same as free.
workspace: optional workspace id, name, or `org-name/workspace-name` when
the same name occurs in two of your orgs (defaults to your default; use
list_workspaces to discover them).
hours: lookback window in hours (default 24), used for whichever of
start/end is not given. The register is an unindexed group-by, so the
window is capped at 31 days and a wider one is refused.
start: optional absolute RFC3339 lower bound (e.g. "2026-08-01T00:00:00Z");
overrides the hours-derived value when given.
end: optional absolute RFC3339 upper bound; overrides the hours-derived
value when given.
sort: "traces" (default), "failed_traces", or "cost" — all descending. A
value outside that set is refused rather than quietly defaulted, since
a wrong ranking under a right-looking header cannot be caught later.
limit: users per page (default 20, server max 100).
q: an EXACT end-user id. Returns that user's row even when they fall outside
the top-N, or an empty register when the window holds nothing for them.
Example:
> Who are my busiest end users this week?
```json
{ "name": "list_users", "arguments": { "hours": 168 } }
```
> Which end users are seeing the most failures?
```json
{ "name": "list_users", "arguments": { "hours": 168, "sort": "failed_traces" } }
```
> Is u_8f2 in the last 30 days at all?
```json
{ "name": "list_users", "arguments": { "hours": 720, "q": "u_8f2" } }
```