How can my coding agent list the end users of an agent in Rius?

Your coding agent lists end users in Rius with the list_users tool on the Rius MCP server. Ask in plain words, such as “Who are my busiest end users this week?”, and the tool returns a ranked table of the people your agents served, with traces, failures and cost. The tool covers a whole workspace. To see the users behind one agent, follow up with that agent’s traces, which carry a user_id column.

How it works

An end user is the person on the other side of your agent, identified by the user.id your SDK stamps. It is not a Rius console login. Spans with no user.id count as anonymous traffic, which list_users reports as its own subject.

list_users takes these main parameters:

• hours: the lookback window, 24 by default. The register is capped at 31 days, and a wider window is refused.
• start and end: absolute RFC3339 bounds that override hours.
• sort: traces (default), failed_traces or cost, all descending. Any other value is refused.
• limit: users per page, 20 by default and 100 at most.
• q: an exact end-user id. It returns that user’s row even outside the top results. It is an equality check, not a substring search.
• workspace: a workspace name or ID. Omit it to use your default workspace.

The list is a ranked top-N. A workspace can hold millions of end users, so the server ranks and caps the register, and q reaches past that cap by exact id.

Three figures need care. Coverage is counted in traces, because one trace can belong to two end users. A null cost means nothing in the window was priced, which is not the same as free. Anonymous traffic is a real row, not an error.

The tool has no agent parameter. Two tools narrow the picture:

• list_agent_traces takes agent and user_id, and its rows show a user_id column.
• user_activity_summary takes a user’s exact user_id and returns that person’s KPIs.

See the tool reference for every argument.

Set it up

1. Connect your coding agent to the Rius MCP server once. In Claude Code, run:

   claude mcp add --transport http rius https://mcp.eu.console.rius-glassflow.com/mcp

   If you use the Rius plugin, it already registers this server as rius. For other clients, or for agents without a browser that need a read-scoped API key, follow MCP.

2. Make sure your agents set user.id on their spans. In Python use rius.user, in TypeScript use withUser. Without it, all traffic shows as anonymous.

3. Ask your coding agent in plain words:

   • “Who are my busiest end users this week?”
   • “Which end users are seeing the most failures?”
   • “Is u_8f2 in the last 30 days at all?”

   Your client picks the tool and arguments. For the first question it sends a call like this:

   { "name": "list_users", "arguments": { "hours": 168 } }

   For the second, it adds "sort": "failed_traces". For the third, it sets "hours": 720 and "q": "u_8f2".

4. To see one agent’s users, ask for that agent’s traces: “Show the failed runs of the planner agent from the last two days.” Your client calls list_agent_traces with agent set, and each row names its end user in the user_id column. Read the agent name off a listing instead of guessing it.

5. To go deeper on one person, ask “What did user u_8f2 experience this week?” Your client calls user_activity_summary with that user_id and hours set to 168.

What you get

• A ranked Markdown table of end users, which your client renders as a table or a summary. It is the same read the console’s Users page makes.
• Per-user figures for traces, failed traces and cost, ordered by the sort you chose.
• An anonymous row for traffic with no end user, so you see how the un-attributed runs are doing.
• A path from a user to evidence. Pass a user_id from the register to user_activity_summary for their KPIs, or to list_agent_traces for their runs, then open a trace with get_agent_trace.
• Failed and errored traces reported as two separate figures in the summary, so a run that retried and recovered is not counted as a failure.

For investigation patterns that combine these tools, see Monitor AI agents in production.

When something else fits

• Use the console’s Users page when you want to browse people visually instead of asking your coding agent.
• Use list_agent_traces with agent when you care about one agent’s runs rather than a ranked list of people.
• Use user_activity_summary when you already have a user id from a complaint and want that person’s experience in one call.

Related