v1 JSON API

The v1 API is the primary HTTP surface used by Grafana, alerting tooling, and any code that talks to Prometheus over HTTP. The implementation is in web/api/v1/api.go. The OpenAPI 3.2 spec is at /openapi.yaml.

Common response shape

{
  "status": "success" | "error",
  "data": <type-specific>,
  "errorType": "<canonical>",
  "error": "...",
  "warnings": [ "..." ],
  "infos":    [ "..." ]
}

warnings and infos are populated from PromQL annotations (see util/annotations). Error types are: timeout, canceled, execution, bad_data, internal, unavailable, not_found, not_acceptable (from web/api/v1/api.go::errorType).

A non-standard 499 is returned when the client closes the connection mid-request (the same convention nginx uses).

Query routes

GET/POST /api/v1/query

Instant query at a point in time.

Parameters: query, time (default: now), timeout, stats=all|count, lookback_delta.

Returns: Vector | Scalar | String | Matrix depending on the expression.

GET/POST /api/v1/query_range

Range query.

Parameters: query, start, end, step, timeout, stats=all|count, lookback_delta.

Returns: Matrix (one series per result, samples per step).

GET/POST /api/v1/query_exemplars

Exemplars matching a query.

Parameters: query, start, end. Requires --enable-feature=exemplar-storage.

GET/POST /api/v1/format_query

Pretty-prints a PromQL expression. Returns { status, data: <pretty> }.

GET/POST /api/v1/parse_query

Returns the parsed AST as JSON (handy for editors).

Series and label routes

Route	Returns
GET/POST /api/v1/series?match[]=	Series matching the matchers, with timestamps.
GET/POST /api/v1/labels	Label names. match[] can scope.
GET /api/v1/label/:name/values	Distinct values for one label, optionally scoped by match[].

Targets and scrape routes

Route	Returns
GET /api/v1/targets	Active and dropped targets, with lastError, lastScrape, health.
GET /api/v1/targets/metadata	Per-target (metric, type, help, unit); supports metric filter.
GET /api/v1/targets/relabel_steps	Per-target step-by-step relabel pipeline output.
GET /api/v1/scrape_pools	Pool list with target counts.
GET /api/v1/metadata	Global metric metadata.

Rules and alerts

Route	Returns
GET /api/v1/rules	Rule groups, recording and alerting rules with last evaluation.
GET /api/v1/alerts	Currently active alerts (pending + firing).

/rules?type=alert|record filters by rule type. /rules?match[]= filters by matcher.

Status routes

Route	Source
GET /api/v1/status/config	Live prometheus.yml content.
GET /api/v1/status/runtimeinfo	RuntimeInfo struct (start time, GOMAXPROCS, etc.).
GET /api/v1/status/buildinfo	Build version, commit, branch, Go version.
GET /api/v1/status/flags	Live CLI flags.
GET /api/v1/status/tsdb	TSDB cardinality stats; server-mode only.
GET /api/v1/status/tsdb/blocks	Block listing.
GET /api/v1/status/walreplay	WAL replay progress.
GET /api/v1/status/self_metrics	Curated subset of self-metrics (3.x).
GET /api/v1/features	Feature flag registry.
GET /api/v1/notifications	UI notifications snapshot.
GET /api/v1/notifications/live	Server-Sent Events feed of UI notifications.

Admin routes

Gated by --web.enable-admin-api:

• POST/PUT /api/v1/admin/tsdb/delete_series — tombstone series.
• POST/PUT /api/v1/admin/tsdb/clean_tombstones — force compaction.
• POST/PUT /api/v1/admin/tsdb/snapshot — snapshot blocks (and head).

Lifecycle routes

Gated by --web.enable-lifecycle:

• POST /-/reload — reload config.
• POST /-/quit — shut down cleanly.
• GET /-/healthy — always 200 if the process is responsive.
• GET /-/ready — 200 only after WAL replay completes; emits X-Prometheus-Stopping when shutting down (3.10 fix #17795).

Federation

GET /federate?match[]=<matcher>&match[]=... returns OpenMetrics text containing the latest sample per matched series within the lookback window. Implemented in web/federate.go. The external_labels of the local Prometheus are added so federated samples are distinguishable.

Codec negotiation

Accept headers can request alternative codecs. The default JSON codec is in web/api/v1/json_codec.go; it preserves NaN/Inf and uses jsoniter under the hood. Streaming protobuf is supported for read-heavy responses (web/api/v1/codec.go).

Compression

Responses are gzip-compressed by default when the client sends Accept-Encoding: gzip. The compression handler is util/httputil.CompressionHandler.

CORS

Set with --web.cors.origin (regexp). Implemented in util/httputil.SetCORS.

Agent mode allowlist

In agent mode, query, series, labels, rules, alerts, and TSDB-status routes return {"status":"error","errorType":"execution","error":"unavailable with Prometheus Agent"}. The remaining routes (build/runtime info, targets, scrape pools, alertmanagers, write/OTLP) function normally.

Stability

API stability is documented in docs/stability.md. Stable endpoints follow semver: a route never changes its response shape across minor versions. New fields can be added; required fields cannot be removed.

See Web subsystem for the route-registration code and Remote write/read for the protobuf endpoints.