HTTP API

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

Format overview

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

Invalid requests that reach the API handlers return a JSON error objectand 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 APIendpoint is reached.

An array of warnings may be returned if there are errors that donot inhibit the request execution. All of the data that was successfullycollected will be returned in the data field.

The JSON response envelope format is as follows:

  1. {
  2.   "status": "success" | "error",
  3.   "data": <data>,
  5.   // Only set if status is "error". The data field may still hold
  6.   // additional data.
  7.   "errorType": "<string>",
  8.   "error": "<string>",
  10.   // Only if there were warnings while executing the request.
  11.   // There will still be data in the data field.
  12.   "warnings": ["<string>"]
  13. }

Input timestamps may be provided either inRFC3339 format or as a Unix timestampin seconds, with optional decimal places for sub-second precision. Outputtimestamps are always represented as Unix timestamps in seconds.

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

<series_selector> placeholders refer to Prometheus time seriesselectors like http_requests_total orhttp_requests_total{method=~"(GET|POST)"} and need to be URL-encoded.

<duration> placeholders refer to Prometheus duration strings of the form[0-9]+[smhdwy]. For example, 5m refers to a duration of 5 minutes.

<bool> placeholders refer to boolean values (strings true and false).

Expression queries

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

Instant queries

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

  1. GET /api/v1/query
  2. 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 andis capped by the value of the -query.timeout flag.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 andContent-Type: application/x-www-form-urlencoded header. This is useful when specifying a largequery that may breach server-side URL character limits.

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

  1. {
  2.   "resultType": "matrix" | "vector" | "scalar" | "string",
  3.   "result": <value>
  4. }

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

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

  1. $ curl 'http://localhost:9090/api/v1/query?query=up&time=2015-07-01T20:10:51.781Z'
  2. {
  3.    "status" : "success",
  4.    "data" : {
  5.       "resultType" : "vector",
  6.       "result" : [
  7.          {
  8.             "metric" : {
  9.                "__name__" : "up",
  10.                "job" : "prometheus",
  11.                "instance" : "localhost:9090"
  12.             },
  13.             "value": [ 1435781451.781, "1" ]
  14.          },
  15.          {
  16.             "metric" : {
  17.                "__name__" : "up",
  18.                "job" : "node",
  19.                "instance" : "localhost:9100"
  20.             },
  21.             "value" : [ 1435781451.781, "0" ]
  22.          }
  23.       ]
  24.    }
  25. }

Range queries

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

  1. GET /api/v1/query_range
  2. POST /api/v1/query_range

URL query parameters:

  • query=<string>: Prometheus expression query string.
  • start=<rfc3339 | unix_timestamp>: Start timestamp.
  • end=<rfc3339 | unix_timestamp>: End timestamp.
  • step=<duration | float>: Query resolution step width in duration format or float number of seconds.
  • timeout=<duration>: Evaluation timeout. Optional. Defaults to andis capped by the value of the -query.timeout flag.You can URL-encode these parameters directly in the request body by using the POST method andContent-Type: application/x-www-form-urlencoded header. This is useful when specifying a largequery that may breach server-side URL character limits.

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

  1. {
  2.   "resultType": "matrix",
  3.   "result": <value>
  4. }

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

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

  1. $ 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'
  2. {
  3.    "status" : "success",
  4.    "data" : {
  5.       "resultType" : "matrix",
  6.       "result" : [
  7.          {
  8.             "metric" : {
  9.                "__name__" : "up",
  10.                "job" : "prometheus",
  11.                "instance" : "localhost:9090"
  12.             },
  13.             "values" : [
  14.                [ 1435781430.781, "1" ],
  15.                [ 1435781445.781, "1" ],
  16.                [ 1435781460.781, "1" ]
  17.             ]
  18.          },
  19.          {
  20.             "metric" : {
  21.                "__name__" : "up",
  22.                "job" : "node",
  23.                "instance" : "localhost:9091"
  24.             },
  25.             "values" : [
  26.                [ 1435781430.781, "0" ],
  27.                [ 1435781445.781, "0" ],
  28.                [ 1435781460.781, "1" ]
  29.             ]
  30.          }
  31.       ]
  32.    }
  33. }

Querying metadata

Finding series by label matchers

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

  1. GET /api/v1/series
  2. POST /api/v1/series

URL query parameters:

  • match[]=<series_selector>: Repeated series selector argument that selects theseries to return. At least one match[] argument must be provided.
  • start=<rfc3339 | unix_timestamp>: Start timestamp.
  • end=<rfc3339 | unix_timestamp>: End timestamp.You can URL-encode these parameters directly in the request body by using the POST method andContent-Type: application/x-www-form-urlencoded header. This is useful when specifying a largeor 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 thatcontain the label name/value pairs which identify each series.

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

  1. $ curl -g 'http://localhost:9090/api/v1/series?' --data-urlencode='match[]=up' --data-urlencode='match[]=process_start_time_seconds{job="prometheus"}'
  2. {
  3.    "status" : "success",
  4.    "data" : [
  5.       {
  6.          "__name__" : "up",
  7.          "job" : "prometheus",
  8.          "instance" : "localhost:9090"
  9.       },
  10.       {
  11.          "__name__" : "up",
  12.          "job" : "node",
  13.          "instance" : "localhost:9091"
  14.       },
  15.       {
  16.          "__name__" : "process_start_time_seconds",
  17.          "job" : "prometheus",
  18.          "instance" : "localhost:9090"
  19.       }
  20.    ]
  21. }

Getting label names

The following endpoint returns a list of label names:

  1. GET /api/v1/labels
  2. POST /api/v1/labels

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

Here is an example.

  1. $ curl 'localhost:9090/api/v1/labels'
  2. {
  3.     "status": "success",
  4.     "data": [
  5.         "__name__",
  6.         "call",
  7.         "code",
  8.         "config",
  9.         "dialer_name",
  10.         "endpoint",
  11.         "event",
  12.         "goversion",
  13.         "handler",
  14.         "instance",
  15.         "interval",
  16.         "job",
  17.         "le",
  18.         "listener_name",
  19.         "name",
  20.         "quantile",
  21.         "reason",
  22.         "role",
  23.         "scrape_job",
  24.         "slice",
  25.         "version"
  26.     ]
  27. }

Querying label values

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

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

The data section of the JSON response is a list of string label values.

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

  1. $ curl http://localhost:9090/api/v1/label/job/values
  2. {
  3.    "status" : "success",
  4.    "data" : [
  5.       "node",
  6.       "prometheus"
  7.    ]
  8. }

Expression query result formats

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

Range vectors

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

  1. [
  2.   {
  3.     "metric": { "<label_name>": "<label_value>", ... },
  4.     "values": [ [ <unix_time>, "<sample_value>" ], ... ]
  5.   },
  6.   ...
  7. ]

Instant vectors

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

  1. [
  2.   {
  3.     "metric": { "<label_name>": "<label_value>", ... },
  4.     "value": [ <unix_time>, "<sample_value>" ]
  5.   },
  6.   ...
  7. ]

Scalars

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

  1. [ <unix_time>, "<scalar_value>" ]

Strings

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

  1. [ <unix_time>, "<string_value>" ]

Targets

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

  1. GET /api/v1/targets

Both the active and dropped targets are part of the response.labels represents the label set after relabelling has occurred.discoveredLabels represent the unmodified labels retrieved during service discovery before relabelling has occurred.

  1. $ curl http://localhost:9090/api/v1/targets
  2. {
  3.   "status": "success",
  4.   "data": {
  5.     "activeTargets": [
  6.       {
  7.         "discoveredLabels": {
  8.           "__address__": "127.0.0.1:9090",
  9.           "__metrics_path__": "/metrics",
  10.           "__scheme__": "http",
  11.           "job": "prometheus"
  12.         },
  13.         "labels": {
  14.           "instance": "127.0.0.1:9090",
  15.           "job": "prometheus"
  16.         },
  17.         "scrapeUrl": "http://127.0.0.1:9090/metrics",
  18.         "lastError": "",
  19.         "lastScrape": "2017-01-17T15:07:44.723715405+01:00",
  20.         "health": "up"
  21.       }
  22.     ],
  23.     "droppedTargets": [
  24.       {
  25.         "discoveredLabels": {
  26.           "__address__": "127.0.0.1:9100",
  27.           "__metrics_path__": "/metrics",
  28.           "__scheme__": "http",
  29.           "job": "node"
  30.         },
  31.       }
  32.     ]
  33.   }
  34. }

Rules

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

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

  1. GET /api/v1/rules
  1. $ curl http://localhost:9090/api/v1/rules
  3. {
  4.     "data": {
  5.         "groups": [
  6.             {
  7.                 "rules": [
  8.                     {
  9.                         "alerts": [
  10.                             {
  11.                                 "activeAt": "2018-07-04T20:27:12.60602144+02:00",
  12.                                 "annotations": {
  13.                                     "summary": "High request latency"
  14.                                 },
  15.                                 "labels": {
  16.                                     "alertname": "HighRequestLatency",
  17.                                     "severity": "page"
  18.                                 },
  19.                                 "state": "firing",
  20.                                 "value": "1e+00"
  21.                             }
  22.                         ],
  23.                         "annotations": {
  24.                             "summary": "High request latency"
  25.                         },
  26.                         "duration": 600,
  27.                         "health": "ok",
  28.                         "labels": {
  29.                             "severity": "page"
  30.                         },
  31.                         "name": "HighRequestLatency",
  32.                         "query": "job:request_latency_seconds:mean5m{job=\"myjob\"} > 0.5",
  33.                         "type": "alerting"
  34.                     },
  35.                     {
  36.                         "health": "ok",
  37.                         "name": "job:http_inprogress_requests:sum",
  38.                         "query": "sum(http_inprogress_requests) by (job)",
  39.                         "type": "recording"
  40.                     }
  41.                 ],
  42.                 "file": "/rules.yaml",
  43.                 "interval": 60,
  44.                 "name": "example"
  45.             }
  46.         ]
  47.     },
  48.     "status": "success"
  49. }

Alerts

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

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

  1. GET /api/v1/alerts
  1. $ curl http://localhost:9090/api/v1/alerts
  3. {
  4.     "data": {
  5.         "alerts": [
  6.             {
  7.                 "activeAt": "2018-07-04T20:27:12.60602144+02:00",
  8.                 "annotations": {},
  9.                 "labels": {
  10.                     "alertname": "my-alert"
  11.                 },
  12.                 "state": "firing",
  13.                 "value": "1e+00"
  14.             }
  15.         ]
  16.     },
  17.     "status": "success"
  18. }

Querying target metadata

The following endpoint returns metadata about metrics currently scraped by targets.This is experimental and might change in the future.

  1. 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 thatcontain metric metadata and the target label set.

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

  1. curl -G http://localhost:9091/api/v1/targets/metadata \
  2.     --data-urlencode 'metric=go_goroutines' \
  3.     --data-urlencode 'match_target={job="prometheus"}' \
  4.     --data-urlencode 'limit=2'
  5. {
  6.   "status": "success",
  7.   "data": [
  8.     {
  9.       "target": {
  10.         "instance": "127.0.0.1:9090",
  11.         "job": "prometheus"
  12.       },
  13.       "type": "gauge",
  14.       "help": "Number of goroutines that currently exist.",
  15.       "unit": ""
  16.     },
  17.     {
  18.       "target": {
  19.         "instance": "127.0.0.1:9091",
  20.         "job": "prometheus"
  21.       },
  22.       "type": "gauge",
  23.       "help": "Number of goroutines that currently exist.",
  24.       "unit": ""
  25.     }
  26.   ]
  27. }

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

  1. curl -G http://localhost:9091/api/v1/targets/metadata \
  2.     --data-urlencode 'match_target={instance="127.0.0.1:9090"}'
  3. {
  4.   "status": "success",
  5.   "data": [
  6.     // ...
  7.     {
  8.       "target": {
  9.         "instance": "127.0.0.1:9090",
  10.         "job": "prometheus"
  11.       },
  12.       "metric": "prometheus_treecache_zookeeper_failures_total",
  13.       "type": "counter",
  14.       "help": "The total number of ZooKeeper failures.",
  15.       "unit": ""
  16.     },
  17.     {
  18.       "target": {
  19.         "instance": "127.0.0.1:9090",
  20.         "job": "prometheus"
  21.       },
  22.       "metric": "prometheus_tsdb_reloads_total",
  23.       "type": "counter",
  24.       "help": "Number of times the database reloaded block data from disk.",
  25.       "unit": ""
  26.     },
  27.     // ...
  28.   ]
  29. }

Alertmanagers

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

  1. GET /api/v1/alertmanagers

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

  1. $ curl http://localhost:9090/api/v1/alertmanagers
  2. {
  3.   "status": "success",
  4.   "data": {
  5.     "activeAlertmanagers": [
  6.       {
  7.         "url": "http://127.0.0.1:9090/api/v1/alerts"
  8.       }
  9.     ],
  10.     "droppedAlertmanagers": [
  11.       {
  12.         "url": "http://127.0.0.1:9093/api/v1/alerts"
  13.       }
  14.     ]
  15.   }
  16. }

Status

Following status endpoints expose current Prometheus configuration.

Config

The following endpoint returns currently loaded configuration file:

  1. GET /api/v1/status/config

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

  1. $ curl http://localhost:9090/api/v1/status/config
  2. {
  3.   "status": "success",
  4.   "data": {
  5.     "yaml": "<content of the loaded config file in YAML>",
  6.   }
  7. }

Flags

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

  1. GET /api/v1/status/flags

All values are in a form of "string".

  1. $ curl http://localhost:9090/api/v1/status/flags
  2. {
  3.   "status": "success",
  4.   "data": {
  5.     "alertmanager.notification-queue-capacity": "10000",
  6.     "alertmanager.timeout": "10s",
  7.     "log.level": "info",
  8.     "query.lookback-delta": "5m",
  9.     "query.max-concurrency": "20",
  10.     ...
  11.   }
  12. }

New in v2.2

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.

We also expose a gRPC API whose definition can be found here. This is experimental and might change in the future.

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.

  1. POST /api/v1/admin/tsdb/snapshot
  2. PUT /api/v1/admin/tsdb/snapshot

URL query parameters:

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

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.

  1. POST /api/v1/admin/tsdb/delete_series
  2. 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:

  1. $ curl -X POST \
  2.   -g 'http://localhost:9090/api/v1/admin/tsdb/delete_series?match[]=up&match[]=process_start_time_seconds{job="prometheus"}'

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.

  1. POST /api/v1/admin/tsdb/clean_tombstones
  2. PUT /api/v1/admin/tsdb/clean_tombstones

This takes no parameters or body.

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

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