metrics
Query a metric time series.
The output shape depends on the metric type:
GAUGE: avg, min, max per bucket; no sum or rate.
SUM: delta sum and rate per bucket (handles cumulative counters with reset detection; the delta sum across the window is the total increase).
SUMMARY: count, sum, and avg per bucket; quantiles are intentionally omitted — SUMMARY quantiles are non-aggregatable across series (and the raw quantiles column is not queryable via run_sql).
HISTOGRAM / EXPONENTIAL_HISTOGRAM: count, sum, min, max, and p50/p90/p95/p99 (windowed, interpolated).
groupBy and filters accept data-point attribute keys (not resource attributes), plus these metric fields: service, source_instance_id, metric_name, type, unit, temporality, is_monotonic (a field wins over an attribute of the same name). Keys must match [A-Za-z0-9_.-]{1,128}. Filter values are safe to pass as-is.
Params: metricName: required — the exact metric name (from list_metrics). service: optional — exact service name (from list_metrics); omit to aggregate the metric across ALL services emitting it. from, to: required — ISO-8601 window boundaries. step: optional — "", units s m h d w mo y (e.g. "30s", "15m", "2h", "1d", "1w", "1mo", "1y"); minimum 10s; omit for a single window per group. groupBy: optional list of attribute keys or metric fields to split results by. filters: optional map of attribute key or metric field → value to narrow the series.
Returns: type, points[], queryStats, step, requestedStep, coarsened, coarsenReason, explorerUrl, and truncatedRows + truncationHint when points were dropped from the end to fit maxChars.
With a step, every bucket of the window is present for every group the result mentions: a bucket the store had no samples for comes back with count 0 (sum and rate 0 for a SUM, avg/min/max null), so a series that stopped ends in empty buckets rather than on its last populated one.
The server may coarsen the step to stay within point caps. The response's "step" field — not the requestedStep — is authoritative for rate math; "coarsened" + "coarsenReason" (SERIES_CAP | TOTAL_CAP | GROUP_OVERFLOW) report what happened.
explorerUrl opens this exact series as a chart in the Fixter UI — attach it when citing the series as evidence to the user (a spike, a drop, an anomaly, a comparison). You may append &agg=<rate|sum|count|avg|min|max|p50|p90|p95|p99> matching the aggregation you actually cite; invalid values degrade silently to the metric type's default. explorerUrl is null when the query used groupBy, filters, or omitted service — the UI page cannot reproduce those views.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | End of window, ISO-8601 instant (exclusive) | |
| from | Yes | Start of window, ISO-8601 instant (inclusive) | |
| step | No | Time bucket <amount><unit>, units: s m h d w mo y (e.g. 30s, 15m, 2h, 1d, 1w, 1mo, 1y); min 10s; omit for one window | |
| filters | No | key=value filters on data-point attributes or metric fields (service, source_instance_id, metric_name, type, unit, temporality, is_monotonic) to narrow the series | |
| groupBy | No | Data-point attribute keys or metric fields (service, source_instance_id, metric_name, type, unit, temporality, is_monotonic) to group by | |
| service | No | Exact service name (from list_metrics); omit to aggregate across all services | |
| maxChars | No | Character budget for the whole response; points are dropped from the end to fit and truncatedRows says how many. Omit for the server ceiling. | |
| metricName | Yes | Metric name (exact, from list_metrics) |