HTTP API

The current stable HTTP API is reachable under /api/v1 on a Prometheus server

Format overview

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

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

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

  // Only if there were warnings while executing the request.
  // There will still be data in the data field.
  "warnings": ["<string>"]
}

Expression queries

Instant queries

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

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

The data section of the query result has the following format

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

Range queries

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.

Expression query result formats

Range vectors

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

Instant vectors

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

Scalars

[ <unix_time>, "<scalar_value>" ]

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

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.

Alerts

The /alerts endpoint returns a list of all active alerts

GET /api/v1/alerts

Status

Build Information

GET /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"
  }
}