Prometheus logo

Prometheus

DocsDownloadCommunitySupport & TrainingBlog

Ctrl + K

GitHub Logo

HTTP API

The current stable HTTP API is reachable under /api/v1 on a Prometheus server. Any non-breaking additions will be added under that endpoint.

OpenAPI Specification

An OpenAPI specification for the HTTP API is available at /api/v1/openapi.yaml. By default, it returns OpenAPI 3.1 for broader compatibility. Use ?openapi_version=3.2 for OpenAPI 3.2, which includes advanced features and endpoints like /api/v1/notifications/live.

This machine-readable specification describes all available endpoints, request parameters, response formats, and schemas.

The OpenAPI specification can be used to:

  • Generate client libraries in various programming languages.
  • Validate API requests and responses.
  • Generate interactive API documentation.
  • Test API endpoints.

Format overview

The API response format is JSON. Every successful API request returns a 2xx status code.

Invalid requests that reach the API handlers return a JSON error object and one of the following HTTP response codes:

  • 400 Bad Request when parameters are missing or incorrect.
  • 422 Unprocessable Entity when an expression can't be executed (RFC4918 ).
  • 503 Service Unavailable when queries time out or abort.

Other non-2xx codes may be returned for errors occurring before the API endpoint is reached.

An array of warnings may be returned if there are errors that do not inhibit the request execution. An additional array of info-level annotations may be returned for potential query issues that may or may not be false positives. All of the data that was successfully collected will be returned in the data field.

The JSON response envelope format is as follows:

{
  "status": "success" | "error",
  "data": <data>,

  // Only set if status is "error". The data field may still hold
  // additional data.
  "errorType": "<string>",
  "error": "<string>",

  // Only set if there were warnings while executing the request.
  // There will still be data in the data field.
  "warnings": ["<string>"],
  // Only set if there were info-level annotations while executing the request.
  "infos": ["<string>"]
}

Generic placeholders are defined as follows:

  • <rfc3339 | unix_timestamp>: Input timestamps may be provided either in RFC3339  format or as a Unix timestamp in seconds, with optional decimal places for sub-second precision. Output timestamps are always represented as Unix timestamps in seconds.
  • <series_selector>: Prometheus time series selectors like http_requests_total or http_requests_total{method=~"(GET|POST)"} and need to be URL-encoded.
  • <duration>: the subset of Prometheus float literals using time units. For example, 5m refers to a duration of 5 minutes.
  • <bool>: boolean values (strings true and false).

Note: Names of query parameters that may be repeated end with [].

Expression queries

Query language expressions may be evaluated at a single instant or over a range of time. The sections below describe the API endpoints for each type of expression query.

Instant queries

The following endpoint evaluates an instant query at a single point in time:

GET /api/v1/query
POST /api/v1/query

URL query parameters:

  • query=<string>: Prometheus expression query string.
  • time=<rfc3339 | unix_timestamp>: Evaluation timestamp. Optional.
  • timeout=<duration>: Evaluation timeout. Optional. Must be positive. Defaults to and is capped by the effective server-side maximum, which is the query_max_duration configuration option when the query-cost feature flag is enabled and the value is set, and otherwise the value of the -query.timeout flag.
  • limit=<number>: Maximum number of returned series. Doesn't affect scalars or strings but truncates the number of series for matrices and vectors. Optional. 0 means disabled.
  • lookback_delta=<duration | float>: Override the lookback period just for this query in duration format or float number of seconds. Optional.
  • stats=<string>: Include query statistics in the response. Supported values are true (basic statistics) and all (additionally includes detailed per-step statistics: timings and sample counts). Any other non-empty value currently behaves like true, but is deprecated, adds a warning to the response, and will be rejected in the next major release. Optional. See Query statistics.
  • cost=<bool>: Include an estimated-versus-actual cost comparison in the response data. Optional. Ignored unless the query-cost feature flag is enabled. It is a plain on/off switch: any value that is not a boolean is an error. See Query statistics.
  • max_series=<number>: Lower the per-query maximum number of series this query may load. Optional. Ignored unless the query-cost feature flag is enabled. It may only lower the operator-set ceiling configured via query_max_series, never raise it: a higher value is rejected with HTTP 400 (bad_data) rather than silently clamped.
  • max_samples_read=<number>: Lower the per-query maximum number of samples this query may read. Optional. Ignored unless the query-cost feature flag is enabled. It may only lower the operator-set ceiling configured via query_max_samples_read, never raise it: a higher value is rejected with HTTP 400 (bad_data) rather than silently clamped.
  • max_query_duration=<duration>: Lower the per-query maximum execution duration. Optional. Ignored unless the query-cost feature flag is enabled. It may only lower the effective duration ceiling, which is query_max_duration when set and otherwise the -query.timeout flag, never raise it: a higher value is rejected with HTTP 400 (bad_data) rather than silently clamped.

Optional HTTP request headers:

  • X-Prometheus-Use-Start-Timestamps: <bool>: Override the engine-level start timestamp processing setting (--promql.use-start-timestamps) for this query. When set to true, functions such as rate() will use start timestamps from ingested data. When set to false, start timestamp processing is disabled for this query. Optional. If omitted, the engine-level default is used.

The current server time is used if the time parameter is omitted.

You can URL-encode these parameters directly in the request body by using the POST method and Content-Type: application/x-www-form-urlencoded header. This is useful when specifying a large query that may breach server-side URL character limits.

The data section of the query result has the following format:

{
  "resultType": "matrix" | "vector" | "scalar" | "string",
  "result": <value>
}

<value> refers to the query result data, which has varying formats depending on the resultType. See the expression query result formats.

The following example evaluates the expression up at the time 2015-07-01T20:10:51.781Z:

curl 'http://localhost:9090/api/v1/query?query=up&time=2015-07-01T20:10:51.781Z'
{
   "status" : "success",
   "data" : {
      "resultType" : "vector",
      "result" : [
         {
            "metric" : {
               "__name__" : "up",
               "job" : "prometheus",
               "instance" : "localhost:9090"
            },
            "value": [ 1435781451.781, "1" ]
         },
         {
            "metric" : {
               "__name__" : "up",
               "job" : "node",
               "instance" : "localhost:9100"
            },
            "value" : [ 1435781451.781, "0" ]
         }
      ]
   }
}

Range queries

The following endpoint evaluates an expression query over a range of time:

GET /api/v1/query_range
POST /api/v1/query_range

URL query parameters:

  • query=<string>: Prometheus expression query string.
  • start=<rfc3339 | unix_timestamp>: Start timestamp, inclusive.
  • end=<rfc3339 | unix_timestamp>: End timestamp, inclusive.
  • step=<duration | float>: Query resolution step width in duration format or float number of seconds.
  • timeout=<duration>: Evaluation timeout. Optional. Must be positive. Defaults to and is capped by the effective server-side maximum, which is the query_max_duration configuration option when the query-cost feature flag is enabled and the value is set, and otherwise the value of the -query.timeout flag.
  • limit=<number>: Maximum number of returned series. Optional. 0 means disabled.
  • lookback_delta=<duration | float>: Override the lookback period just for this query in duration format or float number of seconds. Optional.
  • stats=<string>: Include query statistics in the response. Supported values are true (basic statistics) and all (additionally includes detailed per-step statistics: timings and sample counts). Any other non-empty value currently behaves like true, but is deprecated, adds a warning to the response, and will be rejected in the next major release. Optional. See Query statistics.
  • cost=<bool>: Include an estimated-versus-actual cost comparison in the response data. Optional. Ignored unless the query-cost feature flag is enabled. It is a plain on/off switch: any value that is not a boolean is an error. See Query statistics.
  • max_series=<number>: Lower the per-query maximum number of series this query may load. Optional. Ignored unless the query-cost feature flag is enabled. It may only lower the operator-set ceiling configured via query_max_series, never raise it: a higher value is rejected with HTTP 400 (bad_data) rather than silently clamped.
  • max_samples_read=<number>: Lower the per-query maximum number of samples this query may read. Optional. Ignored unless the query-cost feature flag is enabled. It may only lower the operator-set ceiling configured via query_max_samples_read, never raise it: a higher value is rejected with HTTP 400 (bad_data) rather than silently clamped.
  • max_query_duration=<duration>: Lower the per-query maximum execution duration. Optional. Ignored unless the query-cost feature flag is enabled. It may only lower the effective duration ceiling, which is query_max_duration when set and otherwise the -query.timeout flag, never raise it: a higher value is rejected with HTTP 400 (bad_data) rather than silently clamped.

Optional HTTP request headers:

  • X-Prometheus-Use-Start-Timestamps: <bool>: Override the engine-level start timestamp processing setting (--promql.use-start-timestamps) for this query. When set to true, functions such as rate() will use start timestamps from ingested data. When set to false, start timestamp processing is disabled for this query. Optional. If omitted, the engine-level default is used.

You can URL-encode these parameters directly in the request body by using the POST method and Content-Type: application/x-www-form-urlencoded header. This is useful when specifying a large query that may breach server-side URL character limits.

The data section of the query result has the following format:

{
  "resultType": "matrix",
  "result": <value>
}

For the format of the <value> placeholder, see the range-vector result format.

The following example evaluates the expression up over a 30-second range with a query resolution of 15 seconds.

curl 'http://localhost:9090/api/v1/query_range?query=up&start=2015-07-01T20:10:30.781Z&end=2015-07-01T20:11:00.781Z&step=15s'
{
   "status" : "success",
   "data" : {
      "resultType" : "matrix",
      "result" : [
         {
            "metric" : {
               "__name__" : "up",
               "job" : "prometheus",
               "instance" : "localhost:9090"
            },
            "values" : [
               [ 1435781430.781, "1" ],
               [ 1435781445.781, "1" ],
               [ 1435781460.781, "1" ]
            ]
         },
         {
            "metric" : {
               "__name__" : "up",
               "job" : "node",
               "instance" : "localhost:9091"
            },
            "values" : [
               [ 1435781430.781, "0" ],
               [ 1435781445.781, "0" ],
               [ 1435781460.781, "1" ]
            ]
         }
      ]
   }
}

Query statistics

When the stats parameter is set (e.g. stats=all), the response data includes a stats object with the following structure:

  • timings: Durations (in seconds) for different phases of query execution (e.g. evalTotalTime, execQueueTime).
  • samples:
    • totalQueryableSamples: Logical underlying sample consumption. Each range-vector window counts its underlying samples, including samples consumed inside subqueries. Materialized subquery results are not counted again, while overlapping windows can count the same underlying sample repeatedly.
    • totalQueryableSamplesPerStep: (Only with stats=all and when per-step stats are enabled.) Per-step underlying sample consumption; same semantics as totalQueryableSamples for the equivalent instant query.
    • samplesRead: Samples read by the evaluator, counting only new points when range-vector windows overlap. With query-cost enabled, this includes all subquery reads, even for child steps in gaps between the consumed parent windows. Without it, subquery reads are attributed only to consumed windows. This measures evaluator input rather than physical storage I/O.
    • samplesReadPerStep: (Only with stats=all and when per-step stats are enabled.) Per-step count of samples read (delta semantics for range-vector).
    • seriesTouched: Number of series consumed during execution, summed across selectors. Repeated selectors can count the same series more than once. This allows comparison with the query cost estimate without requesting a second estimation through cost=true.
    • peakSamples: Peak number of samples in memory during evaluation.

Floats count as one sample; native histograms are weighted by their in-memory size. Fixed @ subqueries read their window once, charging reads to the first parent step, while each parent step counts its logical underlying consumption.

The server also exposes two Prometheus metrics: prometheus_engine_query_samples_total (logical underlying sample consumption) and prometheus_engine_query_samples_read_total (samples read). See Per-step stats for the promql-per-step-stats feature flag.

When the query-cost feature flag is enabled, the instant and range query endpoints accept a cost=<bool> parameter. It is a plain on/off switch, not a set of levels: cost=true enables the comparison, and any value that does not parse as a boolean is rejected with HTTP 400 (bad_data). When cost is true, the response data includes an additional cost object comparing estimated storage input with the actual cost measured during execution:

"cost": {
  "estimated": {
    "seriesTouched": 42,
    "samplesRead": 5040
  },
  "actual": {
    "seriesTouched": 40,
    "samplesRead": 4980,
    "peakSamples": 320
  }
}

The estimated seriesTouched and samplesRead values are approximations that can be higher or lower than actual cost: see Query cost for how they are computed and their accuracy limitations. peakSamples is reported only for the actual cost; there is no estimated peakSamples. The comparison is informational: the estimate is never used to reject a query.

Note that requesting cost=true adds some overhead: Prometheus performs an additional cost estimation after building the query and before executing it, including index enumeration and bounded sampling of chunk data. This estimation reserves a query concurrency slot and counts against the query's duration limit, which starts when the query is built, including a shorter max_query_duration, and against a request timeout: if either expires or the client cancels during estimation, the query fails with the usual timeout or cancellation error. If estimation fails for any other reason, the query still runs, and its result is returned with a warning and without a cost comparison.

Query cost

The query cost endpoints require the query-cost feature flag.

The following endpoints estimate the resource cost of a query without executing it, allowing clients to gauge how expensive a query would be before running it:

GET /api/v1/query_cost
POST /api/v1/query_cost
GET /api/v1/query_range_cost
POST /api/v1/query_range_cost

/api/v1/query_cost accepts the same URL query parameters as /api/v1/query, and /api/v1/query_range_cost accepts the same parameters as /api/v1/query_range, so a request accepted by one endpoint is accepted by the other. The parameters that only shape the response of an executed query (limit, stats and cost) are validated in the same way and then ignored, since these endpoints return no query result. As with the other query endpoints, parameters may be URL-encoded in the request body using the POST method with a Content-Type: application/x-www-form-urlencoded header.

The data section of the response has the following format:

{
  "estimate": {
    "seriesTouched": <number>,
    "samplesRead": <number>
  }
}
  • seriesTouched: the number of series the query reads, summed per selector.
  • samplesRead: an estimate of the samplesRead query statistic, the samples the evaluator reads in the engine's sample units, rather than the peak number of samples in memory.

Estimation enumerates matching series in the index and, when supported by storage, samples chunk data to measure sample density and native histogram size. The number of chunk samples is bounded, but index enumeration still scales with selector cardinality and the number of storage blocks. Samples are expressed in the engine's sample units: a float counts as one unit, while native histograms are weighted by their in-memory size.

Estimates include the extra lookback window consumed by anchored and smoothed selectors. Anchored range selectors extend their window by one lookback delta; smoothed range selectors extend it by two. Smoothed instant selectors also read a window spanning two lookback deltas.

Density sampling examines up to 50 chunks in each selector's actual time window. For fully sampled series, the observed sample counts constrain range-selector estimates so that gaps and short-lived series do not imply continuous scraping. A series cut short by the sampling budget contributes only its measured sample interval, including gaps between chunks. Histogram sizing samples up to 50 series and may use a shorter window near the selector's end. These samples may not represent the full population, especially when series have different densities or histogram sizes. Density sampling follows storage iteration order and can favor earlier series or earlier portions of a long query window.

Both values may overestimate or underestimate actual cost. Shared selectors can count the same series repeatedly, indexed series can lack samples in the query window, and sampled density and histogram sizes may not represent all matching series. info() produces an incomplete-estimate warning because its additional runtime-dependent selections are omitted; its second argument is a label filter, not an independent selector.

When remote read is configured, series enumeration also queries the remote read endpoints, and density sampling is unavailable. Estimates then assume the global scrape_interval and float-sized samples, with a warning for each selector that matches series.

Estimation occupies one of the --query.max-concurrency slots for its duration. The deadline also applies while waiting for a slot. It uses query_max_duration when configured and otherwise --query.timeout, unless the request sets a shorter timeout or max_query_duration. Exceeding the deadline returns a timeout error rather than a partial estimate.

curl 'http://localhost:9090/api/v1/query_cost?query=up'
{
   "status" : "success",
   "data" : {
      "estimate" : {
         "seriesTouched" : 42,
         "samplesRead" : 42
      }
   }
}

Estimates are advisory and never used to reject a query. Cost estimation is unavailable in agent mode.

When the query-cost feature flag is enabled, the engine also enforces the reloadable cost limits configured under the global: section of the configuration file (query_max_series, query_max_samples_read, and query_max_duration). These limits are enforced during query execution against the query's actual running cost, not against the estimate above. A query is rejected as soon as the number of series it loads or the number of samples it reads exceeds the configured limit, and query_max_duration surfaces as a query timeout. The estimate returned by these endpoints is informational only and is never used to reject a query.

These limits apply to every query the engine evaluates, not only to API requests. Recording and alerting rules are subject to them too: a rule whose query exceeds a limit fails to evaluate like any other query error, and query_max_duration replaces --query.timeout as the timeout of rule queries.

With query-cost enabled, sample accounting includes all storage input consumed by child evaluators, even when their output falls between outer query windows. Reusing a materialized child result does not charge its storage reads again.

A client may lower any of these ceilings for a single request with the max_series, max_samples_read and max_query_duration parameters. These can only tighten the operator-set value, never loosen it: a request asking for a value above the ceiling is rejected with HTTP 400 (bad_data) so that the caller sees that the limit it asked for was not applied, instead of being silently clamped down. The timeout parameter can also shorten the deadline, but a larger value is capped at the effective duration ceiling rather than rejected.

A query rejected by the series or samples-read limit during execution returns HTTP 422 with the errorType cost_limit, distinguishing a cost rejection from other execution failures. A query stopped by the duration limit usually fails like any other query timeout, with HTTP 503 and the errorType timeout. If the limit expires while the query is still loading series from storage, local or remote, the query can instead fail with HTTP 422 and the errorType execution (expanding series: context deadline exceeded), and is not counted under max_duration below.

The engine also exposes three metrics while the feature flag is enabled: prometheus_engine_query_rejected_total (rejections by reason), prometheus_engine_query_series_touched and prometheus_engine_query_samples_read (per-query distributions). The reason is max_series, max_samples_read or max_duration. max_duration counts queries stopped by query_max_duration or max_query_duration; expiries of --query.timeout or a request timeout are not counted.

Formatting query expressions

The following endpoint formats a PromQL expression in a prettified way:

GET /api/v1/format_query
POST /api/v1/format_query

URL query parameters:

  • query=<string>: Prometheus expression query string.

You can URL-encode these parameters directly in the request body by using the POST method and Content-Type: application/x-www-form-urlencoded header. This is useful when specifying a large query that may breach server-side URL character limits.

The data section of the query result is a string containing the formatted query expression. Note that any comments are removed in the formatted string.

The following example formats the expression foo/bar:

curl 'http://localhost:9090/api/v1/format_query?query=foo/bar'
{
   "status" : "success",
   "data" : "foo / bar"
}

Parsing a PromQL expressions into a abstract syntax tree (AST)

This endpoint is experimental and might change in the future. It is currently only meant to be used by Prometheus' own web UI, and the endpoint name and exact format returned may change from one Prometheus version to another. It may also be removed again in case it is no longer needed by the UI.

The following endpoint parses a PromQL expression and returns it as a JSON-formatted AST (abstract syntax tree) representation:

GET /api/v1/parse_query
POST /api/v1/parse_query

URL query parameters:

  • query=<string>: Prometheus expression query string.

You can URL-encode these parameters directly in the request body by using the POST method and Content-Type: application/x-www-form-urlencoded header. This is useful when specifying a large query that may breach server-side URL character limits.

The data section of the query result is a string containing the AST of the parsed query expression.

The following example parses the expression foo/bar:

curl 'http://localhost:9090/api/v1/parse_query?query=foo/bar'
{
   "data" : {
      "bool" : false,
      "lhs" : {
         "matchers" : [
            {
               "name" : "__name__",
               "type" : "=",
               "value" : "foo"
            }
         ],
         "name" : "foo",
         "offset" : 0,
         "startOrEnd" : null,
         "timestamp" : null,
         "type" : "vectorSelector"
      },
      "matching" : {
         "card" : "one-to-one",
         "include" : [],
         "labels" : [],
         "on" : false
      },
      "op" : "/",
      "rhs" : {
         "matchers" : [
            {
               "name" : "__name__",
               "type" : "=",
               "value" : "bar"
            }
         ],
         "name" : "bar",
         "offset" : 0,
         "startOrEnd" : null,
         "timestamp" : null,
         "type" : "vectorSelector"
      },
      "type" : "binaryExpr"
   },
   "status" : "success"
}

Querying metadata

Prometheus offers a set of API endpoints to query metadata about series and their labels.

NOTE: These API endpoints may return metadata for series for which there is no sample within the selected time range, and/or for series whose samples have been marked as deleted via the deletion API endpoint. The exact extent of additionally returned series metadata is an implementation detail that may change in the future.

Finding series by label matchers

The following endpoint returns the list of time series that match a certain label set.

GET /api/v1/series
POST /api/v1/series

URL query parameters:

  • match[]=<series_selector>: Repeated series selector argument that selects the series to return. At least one match[] argument must be provided.
  • start=<rfc3339 | unix_timestamp>: Start timestamp.
  • end=<rfc3339 | unix_timestamp>: End timestamp.
  • limit=<number>: Maximum number of returned series. Optional. 0 means disabled.

You can URL-encode these parameters directly in the request body by using the POST method and Content-Type: application/x-www-form-urlencoded header. This is useful when specifying a large or dynamic number of series selectors that may breach server-side URL character limits.

The data section of the query result consists of a list of objects that contain the label name/value pairs which identify each series. Note that the start and end times are approximate and the result may contain label values for series which have no samples in the given interval.

The following example returns all series that match either of the selectors up or process_start_time_seconds{job="prometheus"}:

curl -g 'http://localhost:9090/api/v1/series?' --data-urlencode 'match[]=up' --data-urlencode 'match[]=process_start_time_seconds{job="prometheus"}'
{
   "status" : "success",
   "data" : [
      {
         "__name__" : "up",
         "job" : "prometheus",
         "instance" : "localhost:9090"
      },
      {
         "__name__" : "up",
         "job" : "node",
         "instance" : "localhost:9091"
      },
      {
         "__name__" : "process_start_time_seconds",
         "job" : "prometheus",
         "instance" : "localhost:9090"
      }
   ]
}

Getting label names

The following endpoint returns a list of label names:

GET /api/v1/labels
POST /api/v1/labels

URL query parameters:

  • start=<rfc3339 | unix_timestamp>: Start timestamp. Optional.
  • end=<rfc3339 | unix_timestamp>: End timestamp. Optional.
  • match[]=<series_selector>: Repeated series selector argument that selects the series from which to read the label names. Optional.
  • limit=<number>: Maximum number of returned series. Optional. 0 means disabled.

The data section of the JSON response is a list of string label names. Note that the start and end times are approximate and the result may contain label names for series which have no samples in the given interval.

Here is an example.

curl 'localhost:9090/api/v1/labels'
{
    "status": "success",
    "data": [
        "__name__",
        "call",
        "code",
        "config",
        "dialer_name",
        "endpoint",
        "event",
        "goversion",
        "handler",
        "instance",
        "interval",
        "job",
        "le",
        "listener_name",
        "name",
        "quantile",
        "reason",
        "role",
        "scrape_job",
        "slice",
        "version"
    ]
}

Querying label values

The following endpoint returns a list of label values for a provided label name:

GET /api/v1/label/<label_name>/values

URL query parameters:

  • start=<rfc3339 | unix_timestamp>: Start timestamp. Optional.
  • end=<rfc3339 | unix_timestamp>: End timestamp. Optional.
  • match[]=<series_selector>: Repeated series selector argument that selects the series from which to read the label values. Optional.
  • limit=<number>: Maximum number of returned series. Optional. 0 means disabled.

The data section of the JSON response is a list of string label values. Note that the start and end times are approximate and the result may contain label values for series which have no samples in the given interval.

This example queries for all label values for the http_status_code label:

curl http://localhost:9090/api/v1/label/http_status_code/values
{
   "status" : "success",
   "data" : [
      "200",
      "504"
   ]
}

Label names can optionally be encoded using the Values Escaping method, and is necessary if a name includes the / character. To encode a name in this way:

  • Prepend the label with U__.
  • Letters, numbers, and colons appear as-is.
  • Convert single underscores to double underscores.
  • For all other characters, use the UTF-8 codepoint as a hex integer, surrounded by underscores. So becomes _20_ and a . becomes _2e_.

More information about text escaping can be found in the original UTF-8 Proposal document .

This example queries for all label values for the http.status_code label:

curl http://localhost:9090/api/v1/label/U__http_2e_status_code/values
{
   "status" : "success",
   "data" : [
      "200",
      "404"
   ]
}

Searching metric names, label names, and label values

These endpoints are experimental and must be enabled with --enable-feature=search-api.

The following endpoints provide streamed discovery results for metric names, label names, and label values:

GET /api/v1/search/metric_names
POST /api/v1/search/metric_names
GET /api/v1/search/label_names
POST /api/v1/search/label_names
GET /api/v1/search/label_values
POST /api/v1/search/label_values

These endpoints return newline-delimited JSON with content type application/x-ndjson. The stream contract is:

  • Zero or more batch lines, each with a results array and an optional warnings array.
  • The stream then ends with either a trailer line (status, has_more, optional warnings) or an error line (status, errorType, error) if iteration failed mid-stream after the first batch was sent.

Searches return results from supported storage backends. Participating remote-read storage that does not support search contributes a warning instead of results. Secondary search failures also become warnings, while unsupported primary storage makes search unavailable. No-op backends, including remote-read storage excluded by the requested time range, do not contribute warnings. Warnings can indicate incomplete discovery independently of has_more, which only describes truncation of the available results by the requested limit.

{"results":[{"name":"http_requests_total","type":"counter","help":"Total HTTP requests."}]}
{"status":"success","has_more":false}

If an error occurs before streaming starts, the API returns the usual Prometheus JSON error object with a 4xx/5xx status code. If an error occurs after streaming starts, the stream ends with an NDJSON error line in place of the trailer.

Clients must tolerate an abrupt EOF without a trailer (for example, on transport failure or server shutdown) and must ignore unknown fields in the trailer for forward compatibility.

The has_more field in the trailer is informational only: this version of the API does not provide a pagination cursor. To retrieve more results, raise limit (subject to the operator-configured --web.search.max-limit) or narrow the request via match[]. A future version of the API may add a cursor.

Common URL query parameters:

  • match[]=<series_selector>: Repeated series selector used to scope the search. Optional.
  • search[]=<string>: Repeated search string matched against names or values. Multiple values use OR semantics. Optional.
  • fuzz_threshold=<number>: Fuzzy threshold from 0 to 100. Optional. A value of 0 is the lowest fuzzy threshold.
  • fuzz_alg=<subsequence | jarowinkler>: Matching algorithm. Optional. Default is subsequence.
  • case_sensitive=<bool>: Toggle case-sensitive matching. Optional.
  • sort_by=<string>: Sort mode. Supported values depend on the endpoint.
  • sort_dir=<asc | dsc>: Sort direction. Optional. Only valid with sort_by=alpha.
  • include_score=<bool>: Include the relevance score in each result. Optional.
  • start=<rfc3339 | unix_timestamp>: Start timestamp. Optional.
  • end=<rfc3339 | unix_timestamp>: End timestamp. Optional.
  • limit=<number>: Maximum number of returned results. Optional. Default is 100.
  • batch_size=<number>: Preferred number of results per NDJSON batch. Optional. Default is 100. Clamped to 1000 and the effective result limit.

The start and end parameters narrow results to the selected time window. Results may include values from series active slightly outside that window, because Prometheus stores data in fixed-size blocks (typically 2 hours each).

Additional parameters for /api/v1/search/metric_names:

  • include_metadata=<bool>: Include metric metadata in each result.
  • sort_by=<alpha | score>

Metadata is matched by the exact metric name first, then by the metric family name for suffixes supported by that family's type:

  • _total for counters.
  • _bucket, _sum, and _count for histograms.
  • _bucket, _sum, _count, _gsum, and _gcount for gauge histograms.
  • _sum and _count for summaries.
  • _info for info metrics.

A metric family name that already ends with _total or _info is not matched for the same suffix again: e.g. requests_total_total does not get the metadata of a requests_total counter.

The returned type, help, and unit describe the metric family, not the individual series: e.g. http_request_duration_seconds_bucket is reported with type histogram. Matching is done by name against metadata from active targets, so it is best-effort. Metadata fields are omitted when no matching metadata is available.

Additional parameters for /api/v1/search/label_names:

  • sort_by=<alpha | score>

Additional parameters for /api/v1/search/label_values:

  • label=<label_name>: Label name whose values should be searched. Required.
  • sort_by=<alpha | score>

This example searches metric names for autocomplete:

curl -g 'http://localhost:9090/api/v1/search/metric_names?search[]=http_req&sort_by=score&include_metadata=true&limit=5'
{"results":[{"name":"http_requests_total","type":"counter","help":"Total HTTP requests."}]}
{"status":"success","has_more":false}

This example searches label values for the instance label within the up metric:

curl -g 'http://localhost:9090/api/v1/search/label_values?label=instance&match[]=up&search[]=909&sort_by=score'
{"results":[{"value":"localhost:9090"},{"value":"localhost:9091"}]}
{"status":"success","has_more":true}

Querying exemplars

This is experimental and might change in the future. The following endpoint returns a list of exemplars for a valid PromQL query for a specific time range:

GET /api/v1/query_exemplars
POST /api/v1/query_exemplars

URL query parameters:

  • query=<string>: Prometheus expression query string.
  • start=<rfc3339 | unix_timestamp>: Start timestamp.
  • end=<rfc3339 | unix_timestamp>: End timestamp.
curl -g 'http://localhost:9090/api/v1/query_exemplars?query=test_exemplar_metric_total&start=2020-09-14T15:22:25.479Z&end=2020-09-14T15:23:25.479Z'
{
    "status": "success",
    "data": [
        {
            "seriesLabels": {
                "__name__": "test_exemplar_metric_total",
                "instance": "localhost:8090",
                "job": "prometheus",
                "service": "bar"
            },
            "exemplars": [
                {
                    "labels": {
                        "trace_id": "EpTxMJ40fUus7aGY"
                    },
                    "value": "6",
                    "timestamp": 1600096945.479
                }
            ]
        },
        {
            "seriesLabels": {
                "__name__": "test_exemplar_metric_total",
                "instance": "localhost:8090",
                "job": "prometheus",
                "service": "foo"
            },
            "exemplars": [
                {
                    "labels": {
                        "trace_id": "Olp9XHlq763ccsfa"
                    },
                    "value": "19",
                    "timestamp": 1600096955.479
                },
                {
                    "labels": {
                        "trace_id": "hCtjygkIHwAN9vs4"
                    },
                    "value": "20",
                    "timestamp": 1600096965.489
                }
            ]
        }
    ]
}

Expression query result formats

Expression queries may return the following response values in the result property of the data section. <sample_value> placeholders are numeric sample values. JSON does not support special float values such as NaN, Inf, and -Inf, so sample values are transferred as quoted JSON strings rather than raw numbers.

The keys "histogram" and "histograms" only show up if native histograms are present in the response. Their placeholder <histogram> is explained in detail in its own section below.

Range vectors

Range vectors are returned as result type matrix. The corresponding result property has the following format:

[
  {
    "metric": { "<label_name>": "<label_value>", ... },
    "values": [ [ <unix_time>, "<sample_value>" ], ... ],
    "histograms": [ [ <unix_time>, <histogram> ], ... ]
  },
  ...
]

Each series could have the "values" key, or the "histograms" key, or both. For a given timestamp, there will only be one sample of either float or histogram type.

Series are returned sorted by metric. Functions such as sort and sort_by_label have no effect for range vectors.

Instant vectors

Instant vectors are returned as result type vector. The corresponding result property has the following format:

[
  {
    "metric": { "<label_name>": "<label_value>", ... },
    "value": [ <unix_time>, "<sample_value>" ],
    "histogram": [ <unix_time>, <histogram> ]
  },
  ...
]

Each series could have the "value" key, or the "histogram" key, but not both.

Series are not guaranteed to be returned in any particular order unless a function such as sort or sort_by_label is used.

Scalars

Scalar results are returned as result type scalar. The corresponding result property has the following format:

[ <unix_time>, "<scalar_value>" ]

Strings

String results are returned as result type string. The corresponding result property has the following format:

[ <unix_time>, "<string_value>" ]

Native histograms

The <histogram> placeholder used above is formatted as follows.

{
  "count": "<count_of_observations>",
  "sum": "<sum_of_observations>",
  "buckets": [ [ <boundary_rule>, "<left_boundary>", "<right_boundary>", "<count_in_bucket>" ], ... ]
}

The <boundary_rule> placeholder is an integer between 0 and 3 with the following meaning:

  • 0: “open left” (left boundary is exclusive, right boundary in inclusive)
  • 1: “open right” (left boundary is inclusive, right boundary in exclusive)
  • 2: “open both” (both boundaries are exclusive)
  • 3: “closed both” (both boundaries are inclusive)

Note that with the currently implemented bucket schemas, positive buckets are “open left”, negative buckets are “open right”, and the zero bucket (with a negative left boundary and a positive right boundary) is “closed both”.

Scrape pools

The following endpoint returns a list of all configured scrape pools:

GET /api/v1/scrape_pools

The data section of the JSON response is a list of string scrape pool names.

curl http://localhost:9090/api/v1/scrape_pools
{
  "status": "success",
  "data": {
    "scrapePools": [
      "prometheus",
      "node_exporter",
      "blackbox"
    ]
  }
}

New in v2.42

Scrape pool configuration

This endpoint is experimental and might change in the future. It is currently intended for use by Prometheus' own web UI.

The following endpoint returns the effective configuration for a scrape pool. This includes scrape configurations loaded through scrape_config_files. Authentication credentials and other secrets are redacted.

The scrapePool query parameter is required and must contain the name of a configured scrape pool.

GET /api/v1/scrape_pools/config?scrapePool=<scrape_pool_name>

curl -G http://localhost:9090/api/v1/scrape_pools/config \
  --data-urlencode 'scrapePool=prometheus'
{
  "status": "success",
  "data": {
    "yaml": "job_name: prometheus\nscrape_interval: 15s\nscrape_timeout: 10s\nmetrics_path: /metrics\nscheme: http\n"
  }
}

Targets

The following endpoint returns an overview of the current state of the Prometheus target discovery:

GET /api/v1/targets

Both the active and dropped targets are part of the response by default. Dropped targets are subject to keep_dropped_targets limit, if set. labels represents the label set after relabeling has occurred. discoveredLabels represent the unmodified labels retrieved during service discovery before relabeling has occurred.

curl http://localhost:9090/api/v1/targets
{
  "status": "success",
  "data": {
    "activeTargets": [
      {
        "discoveredLabels": {
          "__address__": "127.0.0.1:9090",
          "__metrics_path__": "/metrics",
          "__scheme__": "http",
          "job": "prometheus"
        },
        "labels": {
          "instance": "127.0.0.1:9090",
          "job": "prometheus"
        },
        "scrapePool": "prometheus",
        "scrapeUrl": "http://127.0.0.1:9090/metrics",
        "globalUrl": "http://example-prometheus:9090/metrics",
        "lastError": "",
        "lastScrape": "2017-01-17T15:07:44.723715405+01:00",
        "lastScrapeDuration": 0.050688943,
        "health": "up",
        "scrapeInterval": "1m",
        "scrapeTimeout": "10s"
      }
    ],
    "droppedTargets": [
      {
        "discoveredLabels": {
          "__address__": "127.0.0.1:9100",
          "__always_scrape_classic_histograms__": "false",
          "__convert_classic_histograms_to_nhcb__": "false",
          "__metrics_path__": "/metrics",
          "__scheme__": "http",
          "__scrape_interval__": "1m",
          "__scrape_native_histograms__": "false",
          "__scrape_timeout__": "10s",
          "job": "node"
        },
        "scrapePool": "node"
      }
    ]
  }
}

The state query parameter allows the caller to filter by active or dropped targets, (e.g., state=active, state=dropped, state=any). Note that an empty array is still returned for targets that are filtered out. Other values are ignored.

curl 'http://localhost:9090/api/v1/targets?state=active'
{
  "status": "success",
  "data": {
    "activeTargets": [
      {
        "discoveredLabels": {
          "__address__": "127.0.0.1:9090",
          "__metrics_path__": "/metrics",
          "__scheme__": "http",
          "job": "prometheus"
        },
        "labels": {
          "instance": "127.0.0.1:9090",
          "job": "prometheus"
        },
        "scrapePool": "prometheus",
        "scrapeUrl": "http://127.0.0.1:9090/metrics",
        "globalUrl": "http://example-prometheus:9090/metrics",
        "lastError": "",
        "lastScrape": "2017-01-17T15:07:44.723715405+01:00",
        "lastScrapeDuration": 50688943,
        "health": "up"
      }
    ],
    "droppedTargets": []
  }
}

The scrapePool query parameter allows the caller to filter by scrape pool name.

curl 'http://localhost:9090/api/v1/targets?scrapePool=node_exporter'
{
  "status": "success",
  "data": {
    "activeTargets": [
      {
        "discoveredLabels": {
          "__address__": "127.0.0.1:9091",
          "__metrics_path__": "/metrics",
          "__scheme__": "http",
          "job": "node_exporter"
        },
        "labels": {
          "instance": "127.0.0.1:9091",
          "job": "node_exporter"
        },
        "scrapePool": "node_exporter",
        "scrapeUrl": "http://127.0.0.1:9091/metrics",
        "globalUrl": "http://example-prometheus:9091/metrics",
        "lastError": "",
        "lastScrape": "2017-01-17T15:07:44.723715405+01:00",
        "lastScrapeDuration": 50688943,
        "health": "up"
      }
    ],
    "droppedTargets": []
  }
}

Relabel steps

This endpoint is experimental and might change in the future. It is currently only meant to be used by Prometheus' own web UI, and the endpoint name and exact format returned may change from one Prometheus version to another. It may also be removed again in case it is no longer needed by the UI.

The following endpoint returns a step-by-step list of relabeling rules and their effects on a given target's label set.

GET /api/v1/targets/relabel_steps

URL query parameters:

  • scrapePool=<string>: The scrape pool name of the target, used to determine the relabeling rules to apply. Required.
  • labels=<string>: A JSON object containing the label set of the target before any relabeling is applied. Required.

The following example returns the relabeling steps for a discovered target in the prometheus scrape pool with the label set {"__address__": "localhost:9090", "job": "prometheus"}:

curl -g 'http://localhost:9090/api/v1/targets/relabel_steps?scrapePool=prometheus&labels={"__address__":"localhost:9090","job":"prometheus"}'
{
   "data" : {
      "steps" : [
         {
            "keep" : true,
            "output" : {
               "__address__" : "localhost:9090",
               "env" : "development",
               "job" : "prometheus"
            },
            "rule" : {
               "action" : "replace",
               "regex" : "(.*)",
               "replacement" : "development",
               "separator" : ";",
               "target_label" : "env"
            }
         },
         {
            "keep" : false,
            "output" : {},
            "rule" : {
               "action" : "drop",
               "regex" : "localhost:.*",
               "replacement" : "$1",
               "separator" : ";",
               "source_labels" : [
                  "__address__"
               ]
            }
         }
      ]
   },
   "status" : "success"
}

Rules

The /rules API endpoint returns a list of alerting and recording rules that are currently loaded. In addition it returns the currently active alerts fired by the Prometheus instance of each alerting rule.

As the /rules endpoint is fairly new, it does not have the same stability guarantees as the overarching API v1.

GET /api/v1/rules

URL query parameters:

  • type=alert|record: return only the alerting rules (e.g. type=alert) or the recording rules (e.g. type=record). When the parameter is absent or empty, no filtering is done.
  • rule_name[]=<string>: only return rules with the given rule name. If the parameter is repeated, rules with any of the provided names are returned. If we've filtered out all the rules of a group, the group is not returned. When the parameter is absent or empty, no filtering is done.
  • rule_group[]=<string>: only return rules with the given rule group name. If the parameter is repeated, rules with any of the provided rule group names are returned. When the parameter is absent or empty, no filtering is done.
  • file[]=<string>: only return rules with the given filepath. If the parameter is repeated, rules with any of the provided filepaths are returned. When the parameter is absent or empty, no filtering is done.
  • exclude_alerts=<bool>: only return rules, do not return active alerts.
  • match[]=<label_selector>: only return rules that have configured labels that satisfy the label selectors. If the parameter is repeated, rules that match any of the sets of label selectors are returned. Note that matching is on the labels in the definition of each rule, not on the values after template expansion (for alerting rules). Optional.
  • group_limit=<number>: The group_limit parameter allows you to specify a limit for the number of rule groups that is returned in a single response. If the total number of rule groups exceeds the specified group_limit value, the response will include a groupNextToken property. You can use the value of this groupNextToken property in subsequent requests in the group_next_token parameter to paginate over the remaining rule groups. The groupNextToken property will not be present in the final response, indicating that you have retrieved all the available rule groups. Please note that there are no guarantees regarding the consistency of the response if the rule groups are being modified during the pagination process.
  • group_next_token: the pagination token that was returned in previous request when the group_limit property is set. The pagination token is used to iteratively paginate over a large number of rule groups. To use the group_next_token parameter, the group_limit parameter also need to be present. If a rule group that coincides with the next token is removed while you are paginating over the rule groups, a response with status code 400 will be returned.
curl http://localhost:9090/api/v1/rules
{
    "data": {
        "groups": [
            {
                "rules": [
                    {
                        "alerts": [
                            {
                                "activeAt": "2018-07-04T20:27:12.60602144+02:00",
                                "annotations": {
                                    "summary": "High request latency"
                                },
                                "labels": {
                                    "alertname": "HighRequestLatency",
                                    "severity": "page"
                                },
                                "state": "firing",
                                "value": "1e+00"
                            }
                        ],
                        "annotations": {
                            "summary": "High request latency"
                        },
                        "duration": 600,
                        "health": "ok",
                        "labels": {
                            "severity": "page"
                        },
                        "name": "HighRequestLatency",
                        "query": "job:request_latency_seconds:mean5m{job=\"myjob\"} > 0.5",
                        "type": "alerting"
                    },
                    {
                        "health": "ok",
                        "name": "job:http_inprogress_requests:sum",
                        "query": "sum by (job) (http_inprogress_requests)",
                        "type": "recording"
                    }
                ],
                "file": "/rules.yaml",
                "interval": 60,
                "limit": 0,
                "name": "example"
            }
        ]
    },
    "status": "success"
}

Alerts

The /alerts endpoint returns a list of all active alerts.

As the /alerts endpoint is fairly new, it does not have the same stability guarantees as the overarching API v1.

GET /api/v1/alerts

curl http://localhost:9090/api/v1/alerts
{
    "data": {
        "alerts": [
            {
                "activeAt": "2018-07-04T20:27:12.60602144+02:00",
                "annotations": {},
                "labels": {
                    "alertname": "my-alert"
                },
                "state": "firing",
                "value": "1e+00"
            }
        ]
    },
    "status": "success"
}

Querying target metadata

The following endpoint returns metadata about metrics currently scraped from targets. The endpoint has the limitation that only metadata scraped from targets directly is returned, metadata sent over Remote-Write or OTLP to Prometheus is not included in this endpoint and will not show up on the UI in "Explore Metrics". This is experimental and might change in the future.

GET /api/v1/targets/metadata

URL query parameters:

  • match_target=<label_selectors>: Label selectors that match targets by their label sets. All targets are selected if left empty.
  • metric=<string>: A metric name to retrieve metadata for. All metric metadata is retrieved if left empty.
  • limit=<number>: Maximum number of targets to match.

The data section of the query result consists of a list of objects that contain metric metadata and the target label set.

The following example returns all metadata entries for the go_goroutines metric from the first two targets with label job="prometheus".

curl -G http://localhost:9091/api/v1/targets/metadata \
    --data-urlencode 'metric=go_goroutines' \
    --data-urlencode 'match_target={job="prometheus"}' \
    --data-urlencode 'limit=2'
{
  "status": "success",
  "data": [
    {
      "target": {
        "instance": "127.0.0.1:9090",
        "job": "prometheus"
      },
      "type": "gauge",
      "help": "Number of goroutines that currently exist.",
      "unit": ""
    },
    {
      "target": {
        "instance": "127.0.0.1:9091",
        "job": "prometheus"
      },
      "type": "gauge",
      "help": "Number of goroutines that currently exist.",
      "unit": ""
    }
  ]
}

The following example returns metadata for all metrics for all targets with label instance="127.0.0.1:9090".

curl -G http://localhost:9091/api/v1/targets/metadata \
    --data-urlencode 'match_target={instance="127.0.0.1:9090"}'
{
  "status": "success",
  "data": [
    // ...
    {
      "target": {
        "instance": "127.0.0.1:9090",
        "job": "prometheus"
      },
      "metric": "prometheus_treecache_zookeeper_failures_total",
      "type": "counter",
      "help": "The total number of ZooKeeper failures.",
      "unit": ""
    },
    {
      "target": {
        "instance": "127.0.0.1:9090",
        "job": "prometheus"
      },
      "metric": "prometheus_tsdb_reloads_total",
      "type": "counter",
      "help": "Number of times the database reloaded block data from disk.",
      "unit": ""
    },
    // ...
  ]
}

Querying metric metadata

It returns metadata about metrics currently scraped from targets. However, it does not provide any target information. This is considered experimental and might change in the future.

GET /api/v1/metadata

URL query parameters:

  • limit=<number>: Maximum number of metrics to return.
  • limit_per_metric=<number>: Maximum number of metadata to return per metric.
  • metric=<string>: A metric name to filter metadata for. All metric metadata is retrieved if left empty.

The data section of the query result consists of an object where each key is a metric name and each value is a list of unique metadata objects, as exposed for that metric name across all targets.

The following example returns two metrics. Note that the metric http_requests_total has more than one object in the list. At least one target has a value for HELP that do not match with the rest.

curl -G http://localhost:9090/api/v1/metadata?limit=2
{
  "status": "success",
  "data": {
    "cortex_ring_tokens": [
      {
        "type": "gauge",
        "help": "Number of tokens in the ring",
        "unit": ""
      }
    ],
    "http_requests_total": [
      {
        "type": "counter",
        "help": "Number of HTTP requests",
        "unit": ""
      },
      {
        "type": "counter",
        "help": "Amount of HTTP requests",
        "unit": ""
      }
    ]
  }
}

The following example returns only one metadata entry for each metric.

curl -G http://localhost:9090/api/v1/metadata?limit_per_metric=1
{
  "status": "success",
  "data": {
    "cortex_ring_tokens": [
      {
        "type": "gauge",
        "help": "Number of tokens in the ring",
        "unit": ""
      }
    ],
    "http_requests_total": [
      {
        "type": "counter",
        "help": "Number of HTTP requests",
        "unit": ""
      }
    ]
  }
}

The following example returns metadata only for the metric http_requests_total.

curl -G http://localhost:9090/api/v1/metadata?metric=http_requests_total
{
  "status": "success",
  "data": {
    "http_requests_total": [
      {
        "type": "counter",
        "help": "Number of HTTP requests",
        "unit": ""
      },
      {
        "type": "counter",
        "help": "Amount of HTTP requests",
        "unit": ""
      }
    ]
  }
}

Alertmanagers

The following endpoint returns an overview of the current state of the Prometheus alertmanager discovery:

GET /api/v1/alertmanagers

Both the active and dropped Alertmanagers are part of the response.

curl http://localhost:9090/api/v1/alertmanagers
{
  "status": "success",
  "data": {
    "activeAlertmanagers": [
      {
        "url": "http://127.0.0.1:9090/api/v1/alerts"
      }
    ],
    "droppedAlertmanagers": [
      {
        "url": "http://127.0.0.1:9093/api/v1/alerts"
      }
    ]
  }
}

Status

Following status endpoints expose current Prometheus configuration.

Config

The following endpoint returns currently loaded configuration file:

GET /api/v1/status/config

The config is returned as dumped YAML file. Due to limitation of the YAML library, YAML comments are not included.

curl http://localhost:9090/api/v1/status/config
{
  "status": "success",
  "data": {
    "yaml": "<content of the loaded config file in YAML>",
  }
}

Flags

The following endpoint returns flag values that Prometheus was configured with:

GET /api/v1/status/flags

All values are of the result type string.

curl http://localhost:9090/api/v1/status/flags
{
  "status": "success",
  "data": {
    "alertmanager.notification-queue-capacity": "10000",
    "alertmanager.timeout": "10s",
    "log.level": "info",
    "query.lookback-delta": "5m",
    "query.max-concurrency": "20",
    ...
  }
}

New in v2.2

Runtime Information

The following endpoint returns various runtime information properties about the Prometheus server:

GET /api/v1/status/runtimeinfo

The returned values are of different types, depending on the nature of the runtime property.

curl http://localhost:9090/api/v1/status/runtimeinfo
{
  "status": "success",
  "data": {
    "startTime": "2019-11-02T17:23:59.301361365+01:00",
    "CWD": "/",
    "hostname" : "DESKTOP-717H17Q",
    "serverTime": "2025-01-05T18:27:33Z",
    "reloadConfigSuccess": true,
    "lastConfigTime": "2019-11-02T17:23:59+01:00",
    "timeSeriesCount": 873,
    "corruptionCount": 0,
    "goroutineCount": 48,
    "GOMAXPROCS": 4,
    "GOGC": "",
    "GODEBUG": "",
    "storageRetention": "15d"
  }
}
NOTE: The exact returned runtime properties may change without notice between Prometheus versions.

New in v2.14

Build Information

The following endpoint returns various build information properties about the Prometheus server:

GET /api/v1/status/buildinfo

All values are of the result type string.

curl http://localhost:9090/api/v1/status/buildinfo
{
  "status": "success",
  "data": {
    "version": "2.13.1",
    "revision": "cb7cbad5f9a2823a622aaa668833ca04f50a0ea7",
    "branch": "master",
    "buildUser": "julius@desktop",
    "buildDate": "20191102-16:19:59",
    "goVersion": "go1.13.1"
  }
}
NOTE: The exact returned build properties may change without notice between Prometheus versions.

New in v2.14

TSDB Stats

The following endpoint returns various cardinality statistics about the Prometheus TSDB:

GET /api/v1/status/tsdb

URL query parameters:

  • limit=<number>: Limit the number of returned items to a given number for each set of statistics. By default, 10 items are returned. The maximum allowed limit is 10000.

The data section of the query result consists of:

  • headStats: This provides the following data about the head block of the TSDB:
    • numSeries: The number of series.
    • chunkCount: The number of chunks.
    • minTime: The current minimum timestamp in milliseconds.
    • maxTime: The current maximum timestamp in milliseconds.
  • seriesCountByMetricName: This will provide a list of metrics names and their series count.
  • labelValueCountByLabelName: This will provide a list of the label names and their value count.
  • memoryInBytesByLabelName This will provide a list of the label names and memory used in bytes. Memory usage is calculated by adding the length of all values for a given label name.
  • seriesCountByLabelPair This will provide a list of label value pairs and their series count.
curl http://localhost:9090/api/v1/status/tsdb
{
  "status": "success",
  "data": {
    "headStats": {
      "numSeries": 508,
      "chunkCount": 937,
      "minTime": 1591516800000,
      "maxTime": 1598896800143,
    },
    "seriesCountByMetricName": [
      {
        "name": "net_conntrack_dialer_conn_failed_total",
        "value": 20
      },
      {
        "name": "prometheus_http_request_duration_seconds_bucket",
        "value": 20
      }
    ],
    "labelValueCountByLabelName": [
      {
        "name": "__name__",
        "value": 211
      },
      {
        "name": "event",
        "value": 3
      }
    ],
    "memoryInBytesByLabelName": [
      {
        "name": "__name__",
        "value": 8266
      },
      {
        "name": "instance",
        "value": 28
      }
    ],
    "seriesCountByLabelValuePair": [
      {
        "name": "job=prometheus",
        "value": 425
      },
      {
        "name": "instance=localhost:9090",
        "value": 425
      }
    ]
  }
}

New in v3.6.0

TSDB Blocks

NOTE: This endpoint is experimental and might change in the future. The endpoint name and the exact format of the returned data may change between Prometheus versions. The exact metadata returned by this endpoint is an implementation detail and may change in future Prometheus versions.

The following endpoint returns the list of currently loaded TSDB blocks and their metadata.

GET /api/v1/status/tsdb/blocks

This endpoint returns the following information for each block:

  • ulid: Unique ID of the block.
  • minTime: Minimum timestamp (in milliseconds) of the block.
  • maxTime: Maximum timestamp (in milliseconds) of the block.
  • stats:
    • numSeries: Number of series in the block.
    • numSamples: Number of samples in the block.
    • numChunks: Number of chunks in the block.
  • compaction:
    • level: The compaction level of the block.
    • sources: List of ULIDs of source blocks used to compact this block.
  • version: The block version.
curl http://localhost:9090/api/v1/status/tsdb/blocks
{
  "status": "success",
  "data": {
    "blocks": [
      {
        "ulid": "01JZ8JKZY6XSK3PTDP9ZKRWT60",
        "minTime": 1750860620060,
        "maxTime": 1750867200000,
        "stats": {
          "numSamples": 13701,
          "numSeries": 716,
          "numChunks": 716
        },
        "compaction": {
          "level": 1,
          "sources": [
            "01JZ8JKZY6XSK3PTDP9ZKRWT60"
          ]
        },
        "version": 1
      }
    ]
  }
}

New in v2.15

WAL Replay Stats

The following endpoint returns information about the WAL replay:

GET /api/v1/status/walreplay
  • read: The number of segments replayed so far.
  • total: The total number segments needed to be replayed.
  • progress: The progress of the replay (0 - 100%).
  • state: The state of the replay. Possible states:
    • waiting: Waiting for the replay to start.
    • in progress: The replay is in progress.
    • done: The replay has finished.
curl http://localhost:9090/api/v1/status/walreplay
{
  "status": "success",
  "data": {
    "min": 2,
    "max": 5,
    "current": 40,
    "state": "in progress"
  }
}
NOTE: This endpoint is available before the server has been marked ready and is updated in real time to facilitate monitoring the progress of the WAL replay.

New in v2.28

Self Metrics

NOTE: This endpoint is experimental and might change in the future.

The following endpoint returns Prometheus' own instrumentation metrics from its internal client registry as structured JSON. These are the same metrics that are exposed on the /metrics endpoint in Prometheus text exposition format, but returned as JSON for programmatic access by the web UI.

The response uses the standard ProtoJSON  representation of the io.prometheus.client.MetricFamily protocol buffer message.

GET /api/v1/status/self_metrics

URL query parameters:

  • metric_name_pattern=<string>: A regular expression filter for metric names (fully anchored, like PromQL label matchers). Only metric families whose names fully match the pattern are returned. For example, metric_name_pattern=prometheus_tsdb_.* returns all metric families whose names start with prometheus_tsdb_. Optional. When omitted, all metric families are returned.

Each returned metric family is a ProtoJSON-encoded MetricFamily containing:

  • name: The metric name.
  • help: The metric help string.
  • type: The metric type (COUNTER, GAUGE, SUMMARY, HISTOGRAM, UNTYPED).
  • unit: The metric unit, if set (optional).
  • metric: A list of individual metrics, each containing:
    • label: A list of {name, value} label pairs.
    • gauge, counter, summary, histogram, or untyped: The type-specific metric data.
curl 'http://localhost:9090/api/v1/status/self_metrics?metric_name_pattern=prometheus_build_info'
{
  "status": "success",
  "data": [
    {
      "name": "prometheus_build_info",
      "help": "A metric with a constant '1' value labeled by version, revision, branch, goversion from which prometheus was built, and the goos and goarch for the build.",
      "type": "GAUGE",
      "metric": [
        {
          "label": [
            { "name": "branch", "value": "main" },
            { "name": "goarch", "value": "amd64" },
            { "name": "goos", "value": "linux" },
            { "name": "goversion", "value": "go1.26.1-X:nodwarf5" },
            { "name": "revision", "value": "7b5a4090e38d9e1ad7697c7641234f4ed135a6c7" },
            { "name": "tags", "value": "netgo,builtinassets" },
            { "name": "version", "value": "3.11.0-rc.0" }
          ],
          "gauge": {
            "value": 1
          }
        }
      ]
    }
  ]
}

TSDB Admin APIs

These are APIs that expose database functionalities for the advanced user. These APIs are not enabled unless the --web.enable-admin-api is set.

Snapshot

Snapshot creates a snapshot of all current data into snapshots/<datetime>-<rand> under the TSDB's data directory and returns the directory as response. It will optionally skip snapshotting data that is only present in the head block, and which has not yet been compacted to disk.

POST /api/v1/admin/tsdb/snapshot
PUT /api/v1/admin/tsdb/snapshot

URL query parameters:

  • skip_head=<bool>: Skip data present in the head block. Optional.
curl -XPOST http://localhost:9090/api/v1/admin/tsdb/snapshot
{
  "status": "success",
  "data": {
    "name": "20171210T211224Z-2be650b6d019eb54"
  }
}

The snapshot now exists at <data-dir>/snapshots/20171210T211224Z-2be650b6d019eb54

New in v2.1 and supports PUT from v2.9

Delete Series

DeleteSeries deletes data for a selection of series in a time range. The actual data still exists on disk and is cleaned up in future compactions or can be explicitly cleaned up by hitting the Clean Tombstones endpoint.

If successful, a 204 is returned.

POST /api/v1/admin/tsdb/delete_series
PUT /api/v1/admin/tsdb/delete_series

URL query parameters:

  • match[]=<series_selector>: Repeated label matcher argument that selects the series to delete. At least one match[] argument must be provided.
  • start=<rfc3339 | unix_timestamp>: Start timestamp. Optional and defaults to minimum possible time.
  • end=<rfc3339 | unix_timestamp>: End timestamp. Optional and defaults to maximum possible time.

Not mentioning both start and end times would clear all the data for the matched series in the database.

Example:

curl -X POST \
  -g 'http://localhost:9090/api/v1/admin/tsdb/delete_series?match[]=up&match[]=process_start_time_seconds{job="prometheus"}'
NOTE: This endpoint marks samples from series as deleted, but will not necessarily prevent associated series metadata from still being returned in metadata queries for the affected time range (even after cleaning tombstones). The exact extent of metadata deletion is an implementation detail that may change in the future.

New in v2.1 and supports PUT from v2.9

Clean Tombstones

CleanTombstones removes the deleted data from disk and cleans up the existing tombstones. This can be used after deleting series to free up space.

If successful, a 204 is returned.

POST /api/v1/admin/tsdb/clean_tombstones
PUT /api/v1/admin/tsdb/clean_tombstones

This takes no parameters or body.

curl -XPOST http://localhost:9090/api/v1/admin/tsdb/clean_tombstones

New in v2.1 and supports PUT from v2.9

Remote Write Receiver

Prometheus can be configured as a receiver for the Prometheus remote write protocol. This is not considered an efficient way of ingesting samples. Use it with caution for specific low-volume use cases. It is not suitable for replacing the ingestion via scraping and turning Prometheus into a push-based metrics collection system.

Enable the remote write receiver by setting --web.enable-remote-write-receiver. When enabled, the remote write receiver endpoint is /api/v1/write. Find more details here.

New in v2.33

Remote Read

POST /api/v1/read

Prometheus exposes a remote read endpoint that allows external systems (such as Thanos) to read data from the TSDB.

For more details, see the Remote Read API documentation and the guide on Remote Endpoints and Storage.

OTLP Receiver

Prometheus can be configured as a receiver for the OTLP Metrics protocol. This is not considered an efficient way of ingesting samples. Use it with caution for specific low-volume use cases. It is not suitable for replacing the ingestion via scraping.

Enable the OTLP receiver by setting --web.enable-otlp-receiver. When enabled, the OTLP receiver endpoint is /api/v1/otlp/v1/metrics.

New in v2.47

OTLP Delta

Prometheus can convert incoming metrics from delta temporality to their cumulative equivalent. This is done using deltatocumulative  from the OpenTelemetry Collector.

To enable, pass --enable-feature=otlp-deltatocumulative.

New in v3.2

Notifications

The following endpoints provide information about active status notifications concerning the Prometheus server itself. Notifications are used in the web UI.

These endpoints are experimental. They may change in the future.

Active Notifications

The /api/v1/notifications endpoint returns a list of all currently active notifications.

GET /api/v1/notifications

Example:

curl http://localhost:9090/api/v1/notifications
{
  "status": "success",
  "data": [
    {
      "text": "Prometheus is shutting down and gracefully stopping all operations.",
      "date": "2024-10-07T12:33:08.551376578+02:00",
      "active": true
    }
  ]
}

New in v3.0

Live Notifications

The /api/v1/notifications/live endpoint streams live notifications as they occur, using Server-Sent Events . Deleted notifications are sent with active: false. Active notifications will be sent when connecting to the endpoint.

GET /api/v1/notifications/live

Example:

curl http://localhost:9090/api/v1/notifications/live
data: {
  "status": "success",
  "data": [
    {
      "text": "Prometheus is shutting down and gracefully stopping all operations.",
      "date": "2024-10-07T12:33:08.551376578+02:00",
      "active": true
    }
  ]
}

Note: The /notifications/live endpoint will return a 204 No Content response if the maximum number of subscribers has been reached. You can set the maximum number of listeners with the flag --web.max-notifications-subscribers, which defaults to 16.

GET /api/v1/notifications/live
204 No Content

New in v3.0

Features

The following endpoint returns a list of enabled features in the Prometheus server:

GET /api/v1/features

This endpoint provides information about which features are currently enabled or disabled in the Prometheus instance. Features are organized into categories such as api, promql, promql_functions, etc.

The data section contains a map where each key is a feature category, and each value is a map of feature names to their enabled status (boolean).

curl http://localhost:9090/api/v1/features
{
  "status": "success",
  "data": {
    "api": {
      "admin": false,
      "exclude_alerts": true
    },
    "otlp_receiver": {
      "delta_conversion": false,
      "native_delta_ingestion": false
    },
    "prometheus": {
      "agent_mode": false,
      "auto_reload_config": false
    },
    "promql": {
      "anchored": false,
      "at_modifier": true
    },
    "promql_functions": {
      "abs": true,
      "absent": true
    },
    "promql_operators": {
      "!=": true,
      "!~": true
    },
    "rules": {
      "concurrent_rule_eval": false,
      "keep_firing_for": true
    },
    "scrape": {
      "start_timestamp_zero_ingestion": false,
      "extra_metrics": false
    },
    "service_discovery": {
      "azure": true,
      "consul": true
    },
    "templating": {
      "args": true,
      "externalURL": true
    },
    "tsdb": {
      "delayed_compaction": false,
      "exemplar_storage": false
    }
  }
}

Notes:

  • All feature names use snake_case naming convention
  • Features set to false may be omitted from the response
  • Clients should treat absent features as equivalent to false
  • Clients must ignore unknown feature names and categories for forward compatibility

New in v3.8

On this page