Metrics

Metrics are queried with PromQL. Always discover first — /v1/metrics supplies the exact names, kinds, units, and label dimensions to copy into queries. Don’t guess names.

`GET /v1/metrics` — the catalogue

Lists metrics observed over the last 24 hours by default. Pass since/until to widen discovery up to a 30-day span — useful for finding a metric that stopped emitting days ago — and trust the echoed range_start/range_end.

{
  "project_id": "prj_...",
  "range_start": "...",
  "range_end": "...",
  "metrics": {
    "items": [
      {
        "name": "paymentramp.sessions.active",
        "kind": "gauge",
        "unit": "{session}",
        "dimensions": { "items": [ { "key": "service.name", "values": { "items": [...], "truncated": false } } ], "truncated": false }
      }
    ],
    "truncated": false
  }
}

Truncation semantics: a missing metric is conclusive only when metrics.truncated: false; a missing dimension only when that metric’s dimensions.truncated: false; dimension values are exhaustive only when values.truncated: false. The 200-metric cap is alphabetical, so a wider window can push a busy project past it and drop later-named metrics.

Pick the query idiom from `kind`

Kind	Meaning	Typical PromQL
`gauge`	Point-in-time value	`avg by ("service.name") ({__name__="paymentramp.sessions.active"})`
`sum`	Monotonic counter	`sum by ("service.name") (rate({__name__="paymentramp.order.probe.success"}[5m]))`
`histogram`, `exponential_histogram`	Bucketed distribution	`histogram_quantile(0.99, sum by (le) (rate({__name__="http.server.request.duration_bucket"}[5m])))`

The catalogue lists a histogram’s base name only — append _bucket, _count, or _sum inside the __name__ matcher. histogram_avg, histogram_count, and histogram_sum are also available.
Summaries never appear in the catalogue.
kind cannot distinguish delta-temporality sums from cumulative ones. Querying a delta series returns 400 VALIDATION_ERROR (delta-temporality is not supported here) — that’s terminal for the series; don’t rewrite the expression and retry.

Dotted names need `name` selectors

Names are stored exactly as emitted, and real Mirador names are dotted (mirador.derived.client_slippage_bps) — which makes them invalid as bare PromQL identifiers. Write:

Dotted metric: {__name__="http.server.request.duration"}
Dotted label matcher: {"http.route"="/pay"}
Dotted grouping key: sum by ("http.route") (...)

Copy exact names from the catalogue. __name__ matching must be exact — regex metric-name selection is rejected.

`GET /v1/metrics/query` — instant

Evaluates PromQL at one instant. query is required; time defaults to now.

curl -sS --fail-with-body -G \
  -H "Authorization: Bearer $MIRADOR_SERVER_KEY" \
  --data-urlencode 'query=avg by ("service.name") ({__name__="paymentramp.sessions.active"})' \
  https://api.mirador.org/v1/metrics/query

`GET /v1/metrics/query_range` — range

Evaluates PromQL across a range. query and step are both required — omitting step is a 400. end defaults to now, start to one hour before end; both accept RFC 3339 or relative ages.

curl -sS --fail-with-body -G \
  -H "Authorization: Bearer $MIRADOR_SERVER_KEY" \
  --data-urlencode 'query=avg by ("service.name") ({__name__="paymentramp.sessions.active"})' \
  --data-urlencode 'start=1h' \
  --data-urlencode 'step=5m' \
  https://api.mirador.org/v1/metrics/query_range

Range queries follow Prometheus semantics and include both start and end when they land on the step — a one-hour range at 5m can contain 13 points. Ranges are point-count limited: on QUERY_TOO_BROAD, widen step or shorten the range.

Response envelope

A successful query is the familiar Prometheus shape:

{ "status": "success", "data": { "resultType": "vector", "result": [ { "metric": {...}, "value": [1755500000, "42"] } ] } }

vector: [{metric, value: [unix_seconds, "value"]}]
matrix: [{metric, values: [[unix_seconds, "value"], ...]}]
scalar / string: [unix_seconds, "value"]

Timestamps are Unix seconds and values are strings so NaN, +Inf, and -Inf survive JSON — parse accordingly. An optional top-level warnings array carries non-fatal evaluation notes; surface the text verbatim and treat the result as a success.

A malformed or unsupported query is a 400 VALIDATION_ERROR, not an empty result — and API errors use Mirador’s typed envelope, not Prometheus’s. A successful empty result means the query ran and matched nothing.

Getting Started

Signals

Dashboards & Alerts

Guides

`GET /v1/metrics` — the catalogue

Pick the query idiom from `kind`

Dotted names need `name` selectors

`GET /v1/metrics/query` — instant

`GET /v1/metrics/query_range` — range

Response envelope

Next Steps

Dashboards

Metric alerts

​GET /v1/metrics — the catalogue

​Pick the query idiom from kind

​Dotted names need __name__ selectors

​GET /v1/metrics/query — instant

​GET /v1/metrics/query_range — range

​Response envelope

​Next Steps

Dashboards

Metric alerts

`GET /v1/metrics` — the catalogue

Pick the query idiom from `kind`

Dotted names need `name` selectors

`GET /v1/metrics/query` — instant

`GET /v1/metrics/query_range` — range

Response envelope

Next Steps