Built-in agent metrics
Use built-in metrics to measure agent activity, duration, token consumption, and tool failures without creating a custom metric. Discover the catalog with GET /v2/metrics and use an exact metric name as the path parameter in GET /v2/metrics/{metric_name}.
All 14 metrics below have category agent, origin system, and dimension agent_keys. System metrics cannot be edited or deleted. The public read guide covers permissions, authentication, and time windows.
Observation scope
The stable agent.trace.* names use recorded invoke_agent spans. The count is not a distinct count of trace IDs. Durations measure invocation-span duration, not a sum of every model/tool span in the trace or the duration of an entire session. Token metrics aggregate attributes recorded on invocation spans. Custom token metrics can instead select chat spans, so do not assume the two populations are identical.
Tool metrics use recorded execute_tool spans. Their error count selects calls with a nonempty tool error type. The built-in sources do not exclude sub-agent invocations by session depth. A custom metric using Top-level sessions only can therefore legitimately differ from a built-in total.
Both built-in source families assign observations to five-minute storage bins using span end time. Reads can combine those bins. These are recorded observations, not an assertion that every attempted run has been captured. For the meaning of session, invocation, span, and trace, see the measurement model.
Agent invocation metrics
| Metric name | Measures | Unit | Type |
|---|---|---|---|
agent.trace.count | Number of recorded agent invocation spans | count | counter |
agent.trace.duration_ms | Invocation-span duration at p50, p90, p95, and p99 | ms | percentiles |
agent.trace.duration_avg_ms | Average invocation-span duration | ms | gauge |
agent.trace.duration_max_ms | Longest invocation-span duration | ms | gauge |
agent.trace.error_count | Recorded invocation spans with error status | count | counter |
agent.trace.input_tokens | Input tokens recorded on invocation spans | tokens | counter |
agent.trace.output_tokens | Output tokens recorded on invocation spans | tokens | counter |
agent.trace.cache_read_tokens | Cache-read input tokens recorded on invocation spans | tokens | counter |
agent.trace.session_count | Approximate distinct session IDs on recorded invocation spans | count | gauge |
agent.trace.duration_distribution | Invocation-span durations grouped into duration ranges | ms | distribution |
Tool metrics
| Metric name | Measures | Unit | Type |
|---|---|---|---|
agent.tool.call_count | Number of tool calls made by agents | count | counter |
agent.tool.duration_ms | Tool call duration at p50, p90, p95, and p99 | ms | percentiles |
agent.tool.error_count | Tool calls that returned an error | count | counter |
agent.tool.duration_distribution | Tool call durations grouped into duration ranges | ms | distribution |
Interpret a series
- Counter: count or sum for a time bin. Treat the returned points as bin aggregates, not a process's lifetime counter that needs differencing.
- Gauge: an aggregate such as an average, maximum, or approximate distinct count. Do not sum per-bin session counts to calculate distinct sessions across the entire window. Query a coarser aggregate instead.
- Percentiles: p50, p90, p95, and p99 values for each time bin. A percentile of a larger window is not the average of the smaller bins' percentiles.
- Distribution: counts grouped by value ranges within each time bin. The metric descriptor supplies each range's label and numeric bounds. Only nonzero bins are returned. A descriptor bin missing from a response point has count zero.
For percentile descriptors, the entry's value is a rank such as 0.95. In a series point, the corresponding entry's value is the measured value at that percentile.
Filter by agent
Use dimensions[agent_keys] with an agent key from your account. The plural name agent_keys is the built-in dimension name. A custom metric can use a different user-chosen dimension name, so read that metric's descriptor rather than assuming the same spelling.
Dimension filters select observations and merge matching values into one series. They do not request a group-by response.
For system metrics, the query start must be within the last 30 days and each window must be at most 30 days long. See Time windows and bins.