Skip to main content
Use the Metrics API to inspect OTLP metrics that Squasher stores from /v1/metrics ingest.

​
List metric series

Common query parameters:
  • from - optional ISO 8601 start timestamp
  • to - optional ISO 8601 end timestamp
  • metric_type - optional gauge, sum, hist, or exponential_histogram
  • service_name - optional service filter
  • environment - optional environment filter
  • q - optional case-insensitive search across metric name, unit, and service name
  • limit
  • offset
from and to must be ISO 8601 timestamps with a timezone. If from is omitted, Squasher starts 24 hours before to; if to is omitted, the window ends at the current time. The Metrics API accepts windows up to 30 days and returns 400 before querying storage for invalid, reversed, or oversized windows. Each row returns the metric name, type, unit, service, first/last seen times, point count, and sample count.

​
Get one metric timeline

Required query parameters:
  • metric_name
  • metric_type
Optional query parameters:
  • from
  • to
  • granularity - 1m, 5m, 15m, 1h, 6h, or 1d
  • aggregation - avg, count, p50, p90, p95, p99, or sum
  • service_name
  • environment
A timeline can contain at most 2,000 possible buckets. Choose a coarser granularity when a long window would exceed that cap; for example, use 5m or wider buckets instead of forcing 1m across multiple days. Percentile aggregations work on gauges and sums directly, plus explicit histograms and delta exponential histograms using their stored bucket distributions. Squasher applies OTLP aggregation temporality before charting sums and histograms:
  • Delta points are aggregated as received.
  • Cumulative points are differenced independently per metric series and instrumentation scope. A changed start time is treated as a reset; malformed same-start counter decreases establish a new baseline instead of being counted as an increase.
  • For a cumulative series already running before the requested window, Squasher uses its latest point from the preceding hour as the baseline. If no recent baseline is retained, the first point contributes zero rather than scanning full retention or counting an unknown pre-window increase. A known start inside the window is included, while an OTLP zero-duration unknown-start reset contributes zero.
  • Explicit histogram bucket arrays are differenced per series and merged in ClickHouse before percentile calculation.
Cumulative exponential histogram avg, count, and sum queries use reset-aware count and sum deltas. Explicit percentile timeline requests return 422 UNSUPPORTED_METRIC_TEMPORALITY until differently scaled bucket layouts can be normalized safely; inspect summaries keep the normalized average and omit only those unsupported percentile timelines. Delta exponential histogram percentiles remain available. Example:
Timeline buckets return:
  • time
  • value
  • point_count
  • sample_count

​
Dashboard usage

Open Metrics in a project to investigate OTLP metric series without building a dashboard first. The explorer lets you:
  • Search by metric name, unit, or service
  • Filter by time range, metric type, service, and environment
  • Switch between average, sum, count, and percentile aggregations
  • Compare the latest bucket with the previous bucket and inspect peak, point, and sample counts
  • Pivot into logs and traces with the selected service and environment already applied
The metrics explorer and dashboard widget builder use the same metric timeline surface behind the scenes. If you already publish a custom OTLP metric, you can chart it in Squasher without hardcoding a product-specific widget type. Pick the metric name, metric type, and aggregation you want, then reuse the same series in the API, CLI, and dashboard UI. If you want to store the dashboard itself in code, use the Dashboards API or the Dashboards as Code workflow with the same metric names and aggregations.

​
Inspect one metric

Use this when raw buckets are too noisy and you want the breakdown an operator or coding agent would actually consume. Required query parameters:
  • metric_name
  • metric_type
Optional query parameters:
  • service_name
  • environment
  • from
  • to
Example:
The response includes:
  • highlights - compact takeaways for the metric right now
  • snapshots[].aggregation - avg, p50, p90, and p99
  • snapshots[].latest_value
  • snapshots[].previous_value
  • snapshots[].change_percent
  • snapshots[].recent_points - last few buckets
  • snapshots[].top_points - peak buckets in the selected window

​
CLI and MCP parity

  • squasher metrics inspect
  • MCP Code Mode: call search("metrics.inspect"), then execute the generated request

​
Agent handoff

For agents, prefer metric inspect before exporting long timelines: