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. Defaults to and is capped by 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.

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. Defaults to and is capped by 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.

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: Total number of samples loaded during the query. For range-vector functions over multiple steps, each step counts the full window.
  • totalQueryableSamplesPerStep: (Only with stats=all and when per-step stats are enabled.) Per-step count of samples loaded; same semantics as totalQueryableSamples per step.
  • samplesRead: Total number of samples read (I/O). For range-vector functions in range queries, only new points per step are counted; for other queries this equals totalQueryableSamples.
  • samplesReadPerStep: (Only with stats=all and when per-step stats are enabled.) Per-step count of samples read (delta semantics for range-vector).
  • peakSamples: Peak number of samples in memory during evaluation.

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

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.