Summary KPIs for agent traces over a time window, for the whole workspace or
for ONE agent: trace count, LLM calls, error rate, failed vs errored traces,
sessions, total/average cost, token usage, and latency and TTFT percentiles.
With `group_by="bucket"` it also answers the same figures per time bucket,
the read behind the console's Drift figure, so "is this agent getting slower
or more expensive over the week" is one call.
Scope it with `agent` to get that agent's own numbers. This is the same
read, with the same arguments, that the Rius console's agent page makes,
so a number you report here and a number a human reads there are the same
number — not two measurements that happen to agree.
Read the **Failed traces** and **Errored traces** lines as the two different
questions they are, and do not add them together or report one as "errors":
a run whose ROOT span errored FAILED, while a run that errored somewhere and
then recovered did not. The error rate is errored traces over traces.
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.
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.
service: optional service-name filter (traces that involve this service).
agent: optional exact agent-name filter, matched against the trace's root span
— the same value the `root_agent` column reports on list_agent_traces, so
read a name off a listing rather than guessing one. Agent identity is its
own field, not the service name: a run that declares no agent falls back
to its service name, so equal `root_agent` and `service` are that
fallback, not two facts.
instance: optional exact agent-instance filter, narrowing to one running copy
of `agent`.
filters: optional list of `{"field": ..., "op": ..., "values": [...]}` clauses,
ANDed together and composable with the named parameters above — the same
grammar and the same field registry as list_agent_traces, so a slice you
listed and the summary of that slice cannot disagree. Call
describe_search_catalog before guessing a key; a rejected clause comes
back naming itself.
group_by: optional; `"bucket"` adds one row per time bucket under the
whole-window figures, with the same definitions and composable with every
scope argument above. A trace counts once, whole, in the bucket its first
span opened in, so the rows sum to the whole-window figures. Rows are
sparse: a bucket no trace opened in has NO row, so never read an absent
bucket as zero traces, zero cost or a 0% error rate.
bucket: optional grain for `group_by="bucket"`: `"minute"`, `"hour"` or
`"day"`. Omit it and the server picks from the window (minute up to 2h,
hour up to 48h, day beyond; day buckets open at UTC midnight, so the
first may be partial). A grain that cuts the window into more than 1000
buckets is refused with the count in the message.
Example:
> How did my agents do over the last 24 hours?
```json
{ "name": "agent_traces_summary", "arguments": { "hours": 24 } }
```
> How is the planner agent doing this week?
```json
{
"name": "agent_traces_summary",
"arguments": { "hours": 168, "agent": "planner" }
}
```
> Is one copy of planner worse than the others?
```json
{
"name": "agent_traces_summary",
"arguments": { "agent": "planner", "instance": "inst-planner-01" }
}
```
> Summarize the checkout-agent service this week.
```json
{
"name": "agent_traces_summary",
"arguments": { "hours": 168, "service": "checkout-agent" }
}
```
> What do planner's gpt-4o runs cost?
```json
{
"name": "agent_traces_summary",
"arguments": {
"agent": "planner",
"filters": [{ "field": "model", "op": "eq", "values": ["gpt-4o"] }]
}
}
```
> Is planner getting slower or more expensive over the week?
```json
{
"name": "agent_traces_summary",
"arguments": { "hours": 168, "agent": "planner", "group_by": "bucket" }
}
```
> Summarize traces between two specific dates.
```json
{
"name": "agent_traces_summary",
"arguments": { "start": "2026-08-01T00:00:00Z", "end": "2026-08-08T00:00:00Z" }
}
```
