openapi: 3.1.0
info:
title: Prometheus API
description: Prometheus is an Open-Source monitoring system with a dimensional data model, flexible query language, efficient time series database and modern alerting approach.
contact:
name: Prometheus Community
url: https://prometheus.io/community/
version: 0.0.1-undefined
servers:
- url: /api/v1
paths:
/query:
get:
tags:
- query
summary: Evaluate an instant query
operationId: query
parameters:
- name: limit
in: query
description: The maximum number of metrics to return.
required: false
explode: false
schema:
type: integer
format: int64
examples:
example:
value: 100
- name: time
in: query
description: The evaluation timestamp (optional, defaults to current time).
required: false
explode: false
schema:
oneOf:
- type: string
format: date-time
description: RFC3339 timestamp.
- type: number
format: unixtime
description: Unix timestamp in seconds.
description: Timestamp in RFC3339 format or Unix timestamp in seconds.
examples:
RFC3339:
value: "2026-01-02T13:37:00Z"
epoch:
value: 1767361020
- name: query
in: query
description: The PromQL query to execute.
required: true
explode: false
schema:
type: string
examples:
example:
value: up
- name: timeout
in: query
description: Evaluation timeout. Optional. Defaults to and is capped by the value of the -query.timeout flag.
required: false
explode: false
schema:
oneOf:
- type: string
format: duration
description: Human-readable form such as 15s or 2m30s. Supported units are ms (milliseconds), s (seconds), m (minutes), h (hours), d (days), w (weeks) and y (years).
- type: number
format: float
description: Fractional number of seconds.
description: Duration in human-readable or numeric format.
examples:
duration:
value: 1m30s
number:
value: "90"
- name: lookback_delta
in: query
description: Override the lookback period for this query. Optional.
required: false
explode: false
schema:
oneOf:
- type: string
format: duration
description: Human-readable form such as 15s or 2m30s. Supported units are ms (milliseconds), s (seconds), m (minutes), h (hours), d (days), w (weeks) and y (years).
- type: number
format: float
description: Fractional number of seconds.
description: Duration in human-readable or numeric format.
examples:
duration:
value: 5m
number:
value: "300"
- name: stats
in: query
description: When provided, include query statistics in the response. The special value 'all' enables more comprehensive statistics.
required: false
explode: false
schema:
type: string
examples:
example:
value: all
responses:
"200":
description: Query executed successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/QueryOutputBody'
examples:
vectorResult:
summary: 'Instant vector query: up'
value: {"status": "success", "data": {"resultType": "vector", "result": [{"metric": {"__name__": "up", "instance": "demo.prometheus.io:9090", "job": "prometheus"}, "value": [1767436620, "1"]}, {"metric": {"__name__": "up", "env": "demo", "instance": "demo.prometheus.io:9093", "job": "alertmanager"}, "value": [1767436620, "1"]}]}}
scalarResult:
summary: 'Scalar query: scalar(42)'
value:
data:
result:
- 1767436620
- "42"
resultType: scalar
status: success
matrixResult:
summary: 'Range vector query: up[5m]'
value: {"status": "success", "data": {"resultType": "matrix", "result": [{"metric": {"__name__": "up", "instance": "demo.prometheus.io:9090", "job": "prometheus"}, "values": [[1767436320, "1"], [1767436620, "1"]]}]}}
default:
description: Error executing query.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
tsdbNotReady:
summary: TSDB not ready
value:
error: TSDB not ready
errorType: internal
status: error
post:
tags:
- query
summary: Evaluate an instant query
operationId: query-post
requestBody:
description: Submit an instant query. This endpoint accepts the same parameters as the GET version.
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/QueryPostInputBody'
examples:
simpleQuery:
summary: Simple instant query
value:
query: up
queryWithTime:
summary: Query with specific timestamp
value:
query: up{job="prometheus"}
time: "2026-01-02T13:37:00.000Z"
queryWithLimit:
summary: Query with limit and statistics
value:
limit: 100
query: rate(prometheus_http_requests_total{handler="/api/v1/query"}[5m])
stats: all
required: true
responses:
"200":
description: Instant query executed successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/QueryOutputBody'
examples:
vectorResult:
summary: 'Instant vector query: up'
value: {"status": "success", "data": {"resultType": "vector", "result": [{"metric": {"__name__": "up", "instance": "demo.prometheus.io:9090", "job": "prometheus"}, "value": [1767436620, "1"]}, {"metric": {"__name__": "up", "env": "demo", "instance": "demo.prometheus.io:9093", "job": "alertmanager"}, "value": [1767436620, "1"]}]}}
scalarResult:
summary: 'Scalar query: scalar(42)'
value:
data:
result:
- 1767436620
- "42"
resultType: scalar
status: success
matrixResult:
summary: 'Range vector query: up[5m]'
value: {"status": "success", "data": {"resultType": "matrix", "result": [{"metric": {"__name__": "up", "instance": "demo.prometheus.io:9090", "job": "prometheus"}, "values": [[1767436320, "1"], [1767436620, "1"]]}]}}
default:
description: Error executing instant query.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
tsdbNotReady:
summary: TSDB not ready
value:
error: TSDB not ready
errorType: internal
status: error
/query_range:
get:
tags:
- query
summary: Evaluate a range query
operationId: query-range
parameters:
- name: limit
in: query
description: The maximum number of metrics to return.
required: false
explode: false
schema:
type: integer
format: int64
examples:
example:
value: 100
- name: start
in: query
description: The start time of the query.
required: true
explode: false
schema:
oneOf:
- type: string
format: date-time
description: RFC3339 timestamp.
- type: number
format: unixtime
description: Unix timestamp in seconds.
description: Timestamp in RFC3339 format or Unix timestamp in seconds.
examples:
RFC3339:
value: "2026-01-02T12:37:00Z"
epoch:
value: 1767357420
- name: end
in: query
description: The end time of the query.
required: true
explode: false
schema:
oneOf:
- type: string
format: date-time
description: RFC3339 timestamp.
- type: number
format: unixtime
description: Unix timestamp in seconds.
description: Timestamp in RFC3339 format or Unix timestamp in seconds.
examples:
RFC3339:
value: "2026-01-02T13:37:00Z"
epoch:
value: 1767361020
- name: step
in: query
description: The step size of the query.
required: true
explode: false
schema:
oneOf:
- type: string
format: duration
description: Human-readable form such as 15s or 2m30s. Supported units are ms (milliseconds), s (seconds), m (minutes), h (hours), d (days), w (weeks) and y (years).
- type: number
format: float
description: Fractional number of seconds.
description: Duration in human-readable or numeric format.
examples:
duration:
value: 15s
number:
value: "15"
- name: query
in: query
description: The query to execute.
required: true
explode: false
schema:
type: string
examples:
example:
value: rate(prometheus_http_requests_total{handler="/api/v1/query"}[5m])
- name: timeout
in: query
description: Evaluation timeout. Optional. Defaults to and is capped by the value of the -query.timeout flag.
required: false
explode: false
schema:
oneOf:
- type: string
format: duration
description: Human-readable form such as 15s or 2m30s. Supported units are ms (milliseconds), s (seconds), m (minutes), h (hours), d (days), w (weeks) and y (years).
- type: number
format: float
description: Fractional number of seconds.
description: Duration in human-readable or numeric format.
examples:
duration:
value: 1m30s
number:
value: "90"
- name: lookback_delta
in: query
description: Override the lookback period for this query. Optional.
required: false
explode: false
schema:
oneOf:
- type: string
format: duration
description: Human-readable form such as 15s or 2m30s. Supported units are ms (milliseconds), s (seconds), m (minutes), h (hours), d (days), w (weeks) and y (years).
- type: number
format: float
description: Fractional number of seconds.
description: Duration in human-readable or numeric format.
examples:
duration:
value: 5m
number:
value: "300"
- name: stats
in: query
description: When provided, include query statistics in the response. The special value 'all' enables more comprehensive statistics.
required: false
explode: false
schema:
type: string
examples:
example:
value: all
responses:
"200":
description: Range query executed successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/QueryRangeOutputBody'
examples:
matrixResult:
summary: 'Range query: rate(prometheus_http_requests_total[5m])'
value: {"status": "success", "data": {"resultType": "matrix", "result": [{"metric": {"__name__": "up", "instance": "demo.prometheus.io:9090", "job": "prometheus"}, "values": [[1767433020, "1"], [1767434820, "1"], [1767436620, "1"]]}]}}
default:
description: Error executing range query.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
tsdbNotReady:
summary: TSDB not ready
value:
error: TSDB not ready
errorType: internal
status: error
post:
tags:
- query
summary: Evaluate a range query
operationId: query-range-post
requestBody:
description: Submit a range query. This endpoint accepts the same parameters as the GET version.
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/QueryRangePostInputBody'
examples:
basicRange:
summary: Basic range query
value:
end: "2026-01-02T13:37:00.000Z"
query: up
start: "2026-01-02T12:37:00.000Z"
step: 15s
rateQuery:
summary: Rate calculation over time range
value:
end: "2026-01-02T13:37:00.000Z"
query: rate(prometheus_http_requests_total{handler="/api/v1/query"}[5m])
start: "2026-01-02T12:37:00.000Z"
step: 30s
timeout: 30s
required: true
responses:
"200":
description: Range query executed successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/QueryRangeOutputBody'
examples:
matrixResult:
summary: 'Range query: rate(prometheus_http_requests_total[5m])'
value: {"status": "success", "data": {"resultType": "matrix", "result": [{"metric": {"__name__": "up", "instance": "demo.prometheus.io:9090", "job": "prometheus"}, "values": [[1767433020, "1"], [1767434820, "1"], [1767436620, "1"]]}]}}
default:
description: Error executing range query.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
tsdbNotReady:
summary: TSDB not ready
value:
error: TSDB not ready
errorType: internal
status: error
/query_exemplars:
get:
tags:
- query
summary: Query exemplars
operationId: query-exemplars
parameters:
- name: start
in: query
description: Start timestamp for exemplars query.
required: false
explode: false
schema:
oneOf:
- type: string
format: date-time
description: RFC3339 timestamp.
- type: number
format: unixtime
description: Unix timestamp in seconds.
description: Timestamp in RFC3339 format or Unix timestamp in seconds.
examples:
RFC3339:
value: "2026-01-02T12:37:00Z"
epoch:
value: 1767357420
- name: end
in: query
description: End timestamp for exemplars query.
required: false
explode: false
schema:
oneOf:
- type: string
format: date-time
description: RFC3339 timestamp.
- type: number
format: unixtime
description: Unix timestamp in seconds.
description: Timestamp in RFC3339 format or Unix timestamp in seconds.
examples:
RFC3339:
value: "2026-01-02T13:37:00Z"
epoch:
value: 1767361020
- name: query
in: query
description: PromQL query to extract exemplars for.
required: true
explode: false
schema:
type: string
examples:
example:
value: prometheus_http_requests_total
responses:
"200":
description: Exemplars retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/QueryExemplarsOutputBody'
examples:
exemplarsResult:
summary: Exemplars for a metric with trace IDs
value:
data:
- exemplars:
- labels:
traceID: abc123def456
timestamp: 1.689956451781e+09
value: "1.5"
seriesLabels:
__name__: http_requests_total
job: api-server
method: GET
status: success
default:
description: Error retrieving exemplars.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
tsdbNotReady:
summary: TSDB not ready
value:
error: TSDB not ready
errorType: internal
status: error
post:
tags:
- query
summary: Query exemplars
operationId: query-exemplars-post
requestBody:
description: Submit an exemplars query. This endpoint accepts the same parameters as the GET version.
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/QueryExemplarsPostInputBody'
examples:
basicExemplar:
summary: Query exemplars for a metric
value:
query: prometheus_http_requests_total
exemplarWithTimeRange:
summary: Exemplars within specific time range
value:
end: "2026-01-02T13:37:00.000Z"
query: prometheus_http_requests_total{job="prometheus"}
start: "2026-01-02T12:37:00.000Z"
required: true
responses:
"200":
description: Exemplars query completed successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/QueryExemplarsOutputBody'
examples:
exemplarsResult:
summary: Exemplars for a metric with trace IDs
value:
data:
- exemplars:
- labels:
traceID: abc123def456
timestamp: 1.689956451781e+09
value: "1.5"
seriesLabels:
__name__: http_requests_total
job: api-server
method: GET
status: success
default:
description: Error processing exemplars query.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
tsdbNotReady:
summary: TSDB not ready
value:
error: TSDB not ready
errorType: internal
status: error
/format_query:
get:
tags:
- query
summary: Format a PromQL query
operationId: format-query
parameters:
- name: query
in: query
description: PromQL expression to format.
required: true
explode: false
schema:
type: string
examples:
example:
value: sum(rate(http_requests_total[5m])) by (job)
responses:
"200":
description: Query formatted successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/FormatQueryOutputBody'
examples:
formattedQuery:
summary: Formatted PromQL query
value:
data: sum by(job, status) (rate(http_requests_total[5m]))
status: success
default:
description: Error formatting query.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
tsdbNotReady:
summary: TSDB not ready
value:
error: TSDB not ready
errorType: internal
status: error
post:
tags:
- query
summary: Format a PromQL query
operationId: format-query-post
requestBody:
description: Submit a PromQL query to format. This endpoint accepts the same parameters as the GET version.
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/FormatQueryPostInputBody'
examples:
simpleFormat:
summary: Format a simple query
value:
query: up{job="prometheus"}
complexFormat:
summary: Format a complex query
value:
query: sum(rate(http_requests_total[5m])) by (job, status)
required: true
responses:
"200":
description: Query formatting completed successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/FormatQueryOutputBody'
examples:
formattedQuery:
summary: Formatted PromQL query
value:
data: sum by(job, status) (rate(http_requests_total[5m]))
status: success
default:
description: Error formatting query.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
tsdbNotReady:
summary: TSDB not ready
value:
error: TSDB not ready
errorType: internal
status: error
/parse_query:
get:
tags:
- query
summary: Parse a PromQL query
operationId: parse-query
parameters:
- name: query
in: query
description: PromQL expression to parse.
required: true
explode: false
schema:
type: string
examples:
example:
value: up{job="prometheus"}
responses:
"200":
description: Query parsed successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ParseQueryOutputBody'
examples:
parsedQuery:
summary: Parsed PromQL expression tree
value:
data:
resultType: vector
status: success
default:
description: Error parsing query.
content:
# --- truncated at 32 KB (230 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/prometheus-io/refs/heads/main/openapi/prometheus-server-api-openapi.yml