Aggregate spans
Percentiles, counts and error rates over product spans, bucketed by time and grouped by dimension.
POST
Aggregate spans
Aggregates the spans in a time window into one row per bucket and group. Use it for latency breakdowns per turn or per span, error rates per function or per error type, and trends over hours, days, weeks or months. See the overview for the span, measure and error-type vocabulary.
Request
Headers
Body
Aggregations to compute, one column each:
p50, p95, p99, avg, min, max (over measure), count, error_count, error_rate (errors divided by count, null when count is 0), conversation_count.Per-span value the timing aggregations run over:
duration_ms, time_to_first_token_ms (set on polyai.llm_gateway.provider_call spans) or time_to_first_byte_ms (set on TTS spans). Filter on span_name for the last two: where no span carries the measure, percentiles return 0 and avg/min/max return null.Dimensions to group by, one column each:
span_name, service, layer, project_id, client_env, turn_index, function_name, flow_name, step_name, deployment_version, error_type.Time bucket:
hourly, daily, weekly or monthly. Adds a leading bucket column. Omit for one unbucketed result per group.Restrict to spans that failed for this reason, for example
LLM_PROVIDER_UNAVAILABLE or function_error.Restrict to environments:
test, sandbox, pre-release, live, scenarios. pre-release is the Staging environment.{ "field": "<a group_by or aggs value>", "order": "asc" | "desc" }. Applied after the ascending bucket sort.Response
Column names in row order:
bucket (when interval is set), then each group_by dimension, then each aggregation.Examples
Latency and error rate per span
Time to first token per turn, hourly
Request
Why LLM calls failed
Request
Response
Errors
Last modified on November 10, 2026

