Roll up the latency between two event types into a chart-ready summary.
Pairs each start_event_type event with its matching end_event_type event
and reports the duration between them: bins (a time series over the
window), heatmap (time against latency band), summary (pair count with
p50/p95/p99 and max), events (window totals), and, when
distribution_key_paths is given, a distribution broken down by that key.
This is how the tools, models and hooks pages are drawn.
start_event_type and end_event_type are required and must differ;
anything else returns 400. ts_to defaults to now, and omitting ts_from
spans back to the oldest matching event rather than a fixed window — check
bounds in the response for what was actually covered. bin_count defaults
to 24 and is clamped to 1–168. The distribution names the top 10 keys and
rolls the rest into a single (other) entry, so it still sums to the window
total.
Two behaviours worth knowing. payload_sum_paths can only sum duration_ms,
input_tokens and output_tokens — any other path is ignored silently and
its sums entry stays 0. And sums count only the closing event of each pair,
so token usage reported on both legs is not double-counted.
Authorizations
A scoped AgentEye API key. Mint one in the dashboard under Settings → API keys, or with POST /v1/keys. Each endpoint names the permission it requires; a key without it gets 403 and a required_permission field naming what was missing.
Query Parameters
Required. The event type that opens a span, e.g. tool_use.
Required. The event type that closes it, e.g. tool_result. Must differ from start_event_type.
Comma-separated session ids.
Comma-separated agent ids.
Comma-separated environments.
RFC 3339 lower bound. Omit to span back to the oldest matching event.
RFC 3339 upper bound. Defaults to now.
Time bins on the X axis. Default 24, clamped to 1–168.
success, error, or all (the default, and the fallback for an unrecognized value).
Comma-separated exact model names. Applies to both legs of a pair.
Comma-separated exact tool names. Applies to both legs of a pair.
Comma-separated exact hook names. Applies to both legs of a pair.
Comma-separated exact trigger events. Selects pairs whose opening event carries one of them.
Comma-separated payload keys to group the distribution by, first one present wins, e.g. tool_name,tool. Omit to skip the distribution.
Comma-separated payload keys used to match a start event to its end event, first one present wins. Defaults to tool_call_id,request_id,hook_id,id; events carrying none of them pair in order within their session.
Case-insensitive substring filter on a payload field, written <key>:<text>. Applies to both legs of a pair.
Comma-separated <name>:<field> pairs adding totals under sums. Only duration_ms, input_tokens and output_tokens can be summed.
Response
The latency rollup: bounds, bins, heatmap, summary, events, and optionally distribution.