Endpoints & Conventions

All endpoints are under https://api.mirador.org and require a server key. Responses are scoped to the key’s project.

This page is the practical reference. For the exact, always-current contract — including every schema, bound, and enum — use the Swagger UI, OpenAPI spec, or llms.txt.

Endpoint map

Required parameters are bold; (value) is the default when the parameter is omitted.

Signal	Method and path	Purpose	Parameters
Identity	`GET /v1/identity`	Resolve the key’s organization and project	none
Traces	`GET /v1/traces/tags`	Discover recent trace tags	`since` `(30d ago)`, `until` `(now)`
Traces	`GET /v1/traces/attributes`	Discover recent trace attribute keys and sampled values	`since` `(30d ago)`, `until` `(now)`
Traces	`GET /v1/traces`	Filter and page trace aggregates	`filter`, `since` `(unbounded)`, `until` `(now)`, `page_size` 1–1000 `(100)`, `page_token`
Traces	`GET /v1/traces/{trace_id}`	Read one full trace aggregate	none
Traces	`GET /v1/traces/{trace_id}/events`	Read one trace’s events	none
Logs	`GET /v1/logs/stats`	Exact bucketed counts, groups, and exemplars	`filter`, `since` `(1h ago)`, `until` `(now)`, `interval` `(auto)`, `group_by` ×2, `top_k` 1–20 `(10)`, `exemplars` 0–3 `(1)`
Logs	`GET /v1/logs/attributes`	Discover services and log attribute keys/values	`since` `(24h ago)`, `until` `(now)`
Logs	`GET /v1/logs`	Filter and page log records	`filter`, `since` `(1h ago)`, `until` `(now)`, `page_size` 1–1000 `(100)`, `page_token`
Logs	`GET /v1/logs/stream`	Tail logs as Server-Sent Events (SSE)	`filter`, `window` `(5m)`, `page_size` 1–1000 `(100)`, `heartbeat` 5–60s `(15)`; header `Last-Event-ID`
Metrics	`GET /v1/metrics`	Discover metric names, kinds, units, and dimensions	`since` `(24h ago)`, `until` `(now)`; max span 30d
Metrics	`GET /v1/metrics/query`	Evaluate PromQL at one instant	`query`, `time` `(now)`
Metrics	`GET /v1/metrics/query_range`	Evaluate PromQL across a range	`query`, `step`, `start` `(end - 1h)`, `end` `(now)`
Dashboards	`GET /v1/dashboards`	List dashboard summaries	header `If-None-Match` for 304
Dashboards	`GET /v1/dashboards/{slug}`	Read one complete dashboard and its ETag	none
Dashboards	`PUT /v1/dashboards/{slug}`	Conditionally create or fully replace a dashboard	JSON body; exactly one of `If-None-Match: *` or `If-Match: "<etag>"`
Dashboards	`DELETE /v1/dashboards/{slug}`	Conditionally delete a dashboard	header `If-Match: "<etag>"`
Metric alerts	`GET /v1/metric-alerts`	List metric alert summaries	header `If-None-Match` for 304
Metric alerts	`GET /v1/metric-alerts/{slug}`	Read one metric alert and its ETag	none
Metric alerts	`PUT /v1/metric-alerts/{slug}`	Conditionally create or fully replace a metric alert	JSON body; exactly one of `If-None-Match: *` or `If-Match: "<etag>"`
Metric alerts	`DELETE /v1/metric-alerts/{slug}`	Conditionally delete a metric alert	header `If-Match: "<etag>"`
Channels	`GET /v1/integrations`	List notification channels, redacted	none
Channels	`GET /v1/integrations/{slug}`	Read one notification channel, redacted	none

When composing requests with filters, PromQL, or timestamps, use curl -G --data-urlencode rather than hand-escaping query strings. And prefer -sS --fail-with-body over -f — bare -f discards the response body on errors, hiding the typed {"error": ...} envelope that tells you what to fix.

Time windows

Where supported, since/until, start/end, and metric time accept RFC 3339 (2026-07-27T14:00:00Z) or a relative age (90s, 15m, 2h, 7d). Relative values mean “that long ago.” Pin absolute timestamps when comparing multiple queries — relative windows move between requests. Telemetry since/until windows are half-open: [since, until). Metric range queries follow Prometheus semantics and include both start and end when they land on the step.

Surface	Default window	Maximum span
Trace list	No lower bound (bound it with `since`!)	No cap
Trace tag / attribute catalogues	Last 30 days	30 days
Log records	Last 1 hour	35 days
Log stats	Last 1 hour	7 days
Log attribute catalogue	Last 24 hours	7 days
Log stream replay	`5m`	`window` enum up to `30d`; connection closes after 1 hour
Metric catalogue	Last 24 hours	30 days
Metric range query	Last 1 hour	Point-count limited — widen `step` or shorten the range

Responses echo the window actually read where their schema provides range_start/range_end — trust those values over client-side arithmetic.

Pagination

Trace and log lists are newest-first and use page_size (default 100, range 1–1000) plus an opaque next_page_token. This is cursor pagination, not numbered pagination — there is no page, per_page, or total_pages.

Continue until next_page_token is absent. A short or empty page may still carry a token.
A token carries its resolved window, filter, and page size — GET ...?page_token=<token> is a complete next request. Don’t add since/until alongside a token.
Tokens are signal-specific: never exchange them between trace and log endpoints, and never parse them.

Counting: trace pages include an exact top-level total, so page_size=1 plus total is the cheapest trace count. Log pages have no total — use /v1/logs/stats?interval=whole when you need a log count.

curl -sS --fail-with-body -G \
  -H "Authorization: Bearer $MIRADOR_SERVER_KEY" \
  --data-urlencode "page_token=$NEXT_PAGE_TOKEN" \
  https://api.mirador.org/v1/logs

Filtering

Trace and log filter parameters use AIP-160 expressions. The filterable fields differ per signal — see trace filters and log filters — but the grammar rules are shared:

Quote every value: status="completed", never status=completed.
AND combines fields. OR groups must stay on one field — status="running" OR status="completed" ✅; status="running" OR severity="error" ❌ (400, never silently broadened).
NOT inverts a single leaf.
Attribute dots are literal key characters, not paths. attribute.header.country="US" and the canonical attribute."header.country"="US" both address the key header.country. Quote keys containing hyphens.
Missing and empty compare equally with =: attribute.k="" matches records where k is absent, and attribute.k!="x" includes them. Use attribute.k:* (present) and NOT attribute.k:* (absent) to distinguish presence from absence.
The decoded expression may contain at most 4096 UTF-8 bytes; an OR group holds at most 64 values of ≤256 bytes each; at most 16 attribute-equality predicates per query.
Discover keys before filtering — use the trace and log catalogues rather than guessing names. Sampled values are hints, not exhaustive sets.

# Error traces from US users in the last hour (decoded for readability)
filter=severity="error" AND attribute."header.country"="US"
since=1h

# Anything tagged prod or staging
filter=tag="prod" OR tag="staging"

# Traces where the attribute was never set
filter=NOT attribute.chain:*

URL-encode the filter value when issuing the request — or let curl -G --data-urlencode do it.

Errors

Every error, including rate limiting, uses a typed envelope. Switch on the stable error.code, not the human-readable message. Every 500 includes error.details[0].request_id — quote it when reporting an issue.

{ "error": { "code": "INVALID_FILTER", "message": "...", "details": [] } }

Code	HTTP	What to do
`INVALID_FILTER`	400	Don’t retry the same filter — re-discover names from the catalogue, re-quote values, fix the grammar the message names.
`INVALID_ARGUMENT`	400	Fix the named parameter — malformed, out of bounds, or contradicting a page token.
`QUERY_TOO_BROAD`	400	Widen metric `step`, shorten the range, or drop a grouping dimension, then retry once.
`VALIDATION_ERROR`	400, 413, 415	400 — fix the named field; 413 — body exceeds 1 MiB; 415 — set `Content-Type: application/json`.
`UNAUTHENTICATED`	401	Add `Authorization: Bearer mir_srv_...`.
`PERMISSION_DENIED`	403	Terminal — check the key type; the API rejects `mir_web_*` keys.
`TRACE_NOT_FOUND`	404	Stop on that trace. Covers absent, deleted, and out-of-scope alike — deliberately indistinguishable.
`NOT_FOUND`	404	The dashboard/alert slug is absent in this project (read path only).
`PRECONDITION_FAILED`	412	Another writer won — re-`GET` the target, reapply your intent, retry.
`PRECONDITION_REQUIRED`	428	Add exactly one of `If-None-Match: *` (create) or `If-Match: "<etag>"` (replace/delete).
`TOO_MANY_REQUESTS`	429	Sleep `Retry-After` seconds, then retry.
`UNAVAILABLE`	503	Retry with backoff.
`DEADLINE_EXCEEDED`	504	Narrow the query — shorter range, coarser `step`/`interval` — then retry.
`INTERNAL` / `UNSPECIFIED`	500	Retry once; if it repeats, report `error.details[0].request_id`.

Next Steps

Traces

Discovery, trace filters, aggregates, and events

Logs

Stats, records, log filters, and the SSE stream

Metrics

The metric catalogue and PromQL queries

Getting Started

Signals

Dashboards & Alerts

Guides

Endpoints & Conventions

Endpoint map

Time windows

Filtering

Errors

Next Steps

Traces

Logs

Metrics

​Endpoint map

​Time windows

​Pagination

​Filtering

​Errors

​Next Steps

Traces

Logs

Metrics

Endpoint map

Time windows

Pagination

Filtering

Errors

Next Steps