List End Users
list_usersThe 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?
{ "name": "list_users", "arguments": { "hours": 168 } }Which end users are seeing the most failures?
{ "name": "list_users", "arguments": { "hours": 168, "sort": "failed_traces" } }Is u_8f2 in the last 30 days at all?
{ "name": "list_users", "arguments": { "hours": 720, "q": "u_8f2" } }Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | ||
| end | No | ||
| sort | No | traces | |
| hours | No | ||
| limit | No | ||
| start | No | ||
| workspace | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |