How can my coding agent search an agent’s traces in Rius?

Your coding agent searches an agent’s traces in Rius by calling the list_agent_traces tool on the Rius MCP server. You ask in plain words, such as “show me checkout-agent’s failed runs from the last two days”, and the client fills in the tool arguments for you. The reply is a Markdown table of traces, newest first, and each row carries a trace_id you can open with get_agent_trace.

How it works

The Rius MCP server exposes list_agent_traces, which returns one row per trace as a Markdown table, newest first. Your client reads your question and picks the arguments itself. You rarely call the tool by hand.

The main parameters:

• agent: the exact agent name, matched against the trace’s root span. Read the name off list_agents or off the root_agent column of a listing instead of guessing it. A run that declares no agent falls back to its service name.
• hours: a lookback window ending now, 24 by default. “This week” is hours: 168. Use start and end (RFC3339 timestamps) for an exact range.
• status: Ok, Error or Incomplete. A trace reads Error when any of its spans errored, so a run that retried a failing step and then succeeded is included.
• root_status: the verdict of the root span alone. root_status set to Error finds the runs that genuinely failed. status set to Error with root_status set to Ok finds the runs that hit errors but finished cleanly.
• error_text: free text over the failure itself, so you can find a trace by what it said, such as “rate limit”.
• search: a case-insensitive match on span name, span id, trace id or session id.
• service, instance, user_id and anonymous: narrow to a service, one running copy of an agent, or one end user.
• filters: a list of clauses, each with a field, an operator and values, combined with AND. The fields status, agent, service, model, span_kind, operation and session_id are cheap over any window. Keys that start with attr. or resource. reach your own attributes, cost about ten times more, and work only over windows of 31 days or less. Call describe_search_catalog before guessing a key.
• limit and cursor: 20 rows by default. When more traces match, the reply carries a next-page cursor that you pass back as cursor.

workspace is optional on every call. Omit it to use your default workspace.

Set it up

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

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

The OAuth sign-in opens the first time a session uses the server. If you use the Rius plugin for Claude Code, Codex (beta) or Cursor (beta), it already registers the server as rius. For agents that run without a browser, use a read-scoped API key. Ingest keys cannot query. The MCP page covers every client and the headless setup.

2. Check the connection by asking “Who am I in Rius, and which workspaces can I access?” Your client should call get_me.

3. Find the agent’s name. Ask “Which of my agents are running right now?” to use list_agents, or read the root_agent column from an unfiltered trace list. An agent that sends traces but no heartbeat does not appear in list_agents, so use the trace list for it.

4. Ask for the traces in plain words. For example, “Show me the failed runs from the last two days” becomes:

{ "name": "list_agent_traces", "arguments": { "hours": 48, "status": "Error" } }

5. Narrow it. “Why did checkout-agent start failing at 14:00?” becomes a call with an agent, a time range, both status filters and an error text:

{
    "name": "list_agent_traces",
    "arguments": {
        "agent": "checkout-agent", "status": "Error", "root_status": "Error",
        "start": "2026-09-16T14:00:00Z", "end": "2026-09-16T15:00:00Z",
        "error_text": "rate limit"
    }
}

6. Open one trace. Ask “Break down trace 4bf92f3577b34da6a3ce929d0e0e4736 for me”, and your client calls get_agent_trace with the trace_id from the table. Add include_content to see what the model said or what a tool returned. Spans exported without content have nothing extra to show.

The tool reference lists every argument and more example calls.

What you get

• A table of matching traces with the trace_id, the root agent, the session, the root status and who sent the trace (sent_by). A Silent failure column flags traces the failure detectors reported on.
• Newest-first results, with a cursor for the next page, so your agent can work through a long list without one oversized reply.
• A trace_id on every row that feeds get_agent_trace, which returns the span waterfall, in time order and indented by depth.
• Filters that compose, so a slice you list and the slice you later summarize with agent_traces_summary use the same grammar. To search spans across traces instead, for example every errored tool call in a day, use list_spans.
• A way to investigate from your editor or terminal instead of the console. To place this in a wider workflow, see Monitor AI agents in production.

When something else fits

• If you want rollup numbers (trace count, error rate, cost, latency) rather than a list of runs, ask for agent_traces_summary, which takes the same agent, hours and filters arguments.
• If you want to read a single run in full, go straight to get_agent_trace with its trace_id, or open the trace in the Rius console to browse the waterfall visually.

Related