Prometheus

Prometheus query API

Query and evaluate PromQL expressions.

GitHub OpenAPI

Documentation

📖
Documentation
https://prometheus.io/docs/prometheus/latest/querying/api/
📖
Documentation
https://prometheus.io/docs/prometheus/latest/querying/basics/
📖
Documentation
https://prometheus.io/docs/prometheus/latest/querying/operators/
📖
Documentation
https://prometheus.io/docs/prometheus/latest/querying/functions/
📖
Documentation
https://github.com/prometheus/alertmanager/blob/main/api/v2/openapi.yaml
📖
Documentation
https://prometheus.io/docs/alerting/latest/alertmanager/

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/prometheus-io/refs/heads/main/openapi/prometheus-io-query-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/prometheus-io/refs/heads/main/json-schema/prometheus-query-result-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/prometheus-io/refs/heads/main/json-schema/prometheus-target-schema.json

Other Resources

🔗
JSONLD
https://raw.githubusercontent.com/api-evangelist/prometheus-io/refs/heads/main/json-ld/prometheus-io-context.jsonld
🔗
Examples
https://raw.githubusercontent.com/api-evangelist/prometheus-io/refs/heads/main/examples/prometheus-query-example.json
🔗
Examples
https://raw.githubusercontent.com/api-evangelist/prometheus-io/refs/heads/main/examples/prometheus-query-range-example.json
🔗
Examples
https://raw.githubusercontent.com/api-evangelist/prometheus-io/refs/heads/main/examples/prometheus-targets-example.json
🔗
GraphQL
https://raw.githubusercontent.com/api-evangelist/prometheus-io/refs/heads/main/graphql/prometheus-io-graphql.md

OpenAPI Specification

prometheus-io-query-api-openapi.yml Raw ↑ 
swagger: '2.0'
info:
  version: 0.0.1
  title: Alertmanager admin query API
  description: API of the Prometheus Alertmanager (https://github.com/prometheus/alertmanager)
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
basePath: /api/v2/
consumes:
- application/json
produces:
- application/json
tags:
- name: query
  description: Query and evaluate PromQL expressions.
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: 1689956451.781
                        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: 1689956451.781
                        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:
            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: Parse a PromQL query
      operationId: parse-query-post
      requestBody:
        description: Submit a PromQL query to parse. This endpoint accepts the same parameters as the GET version.
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ParseQueryPostInputBody'
            examples:
              simpleParse:
                summary: Parse a simple query
                value:
                  query: up
              complexParse:
                summary: Parse a complex query
                value:
                  query: rate(http_requests_total{job="api"}[5m])
        required: true
      responses:
        '200':
          description: Query parsed successfully via POST.
          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 via POST.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                tsdbNotReady:
                  summary: TSDB not ready
                  value:
                    error: TSDB not ready
                    errorType: internal
                    status: error
components:
  schemas:
    QueryExemplarsOutputBody:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
          - error
          description: Response status.
          example: success
        data:
          description: Response data (structure varies by endpoint).
          example:
            result: ok
        warnings:
          type: array
          items:
            type: string
          description: Only set if there were warnings while executing the request. There will still be data in the data field.
        infos:
          type: array
          items:
            type: string
          description: Only set if there were info-level annotations while executing the request.
      required:
      - status
      - data
      additionalProperties: false
      description: Generic response body.
    HistogramSeries:
      type: object
      properties:
        metric:
          $ref: '#/components/schemas/Labels'
        histograms:
          type: array
          items:
            type: array
            items:
              oneOf:
              - type: number
              - $ref: '#/components/schemas/HistogramValue'
            maxItems: 2
            minItems: 2
          description: Array of [timestamp, histogramObject] pairs for histogram values.
      required:
      - metric
      - histograms
      additionalProperties: false
      description: A time series with native histogram values.
    FloatSeries:
      type: object
      properties:
        metric:
          $ref: '#/components/schemas/Labels'
        values:
          type: array
          items:
            type: array
            items:
              oneOf:
              - type: number
              - type: string
            maxItems: 2
            minItems: 2
          description: Array of [timestamp, stringValue] pairs for float values.
      required:
      - metric
      - values
      additionalProperties: false
      description: A time series with float values.
    FormatQueryPostInputBody:
      type: object
      properties:
        query:
          type: string
          description: 'Form field: The query to format.'
          example: sum(rate(http_requests_total[5m])) by (status)
      required:
      - query
      additionalProperties: false
      description: POST request body for format query.
    FloatSample:
      type: object
      properties:
        metric:
          $ref: '#/components/schemas/Labels'
        value:
          type: array
          items:
            oneOf:
            - type: number
            - type: string
          maxItems: 2
          minItems: 2
          description: Timestamp and float value as [unixTimestamp, stringValue].
          example:
          - 1767436620
          - '1'
      required:
      - metric
      - value
      additionalProperties: false
      description: A sample with a float value.
    QueryOutputBody:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
          - error
          description: Response status.
          example: success
        data:
          $ref: '#/components/schemas/QueryData'
        warnings:
          type: array
          items:
            type: string
          description: Only set if there were warnings while executing the request. There will still be data in the data field.
        infos:
          type: array
          items:
            type: string
          description: Only set if there were info-level annotations while executing the request.
      required:
      - status
      - data
      additionalProperties: false
      description: Response body for instant query.
    QueryPostInputBody:
      type: object
      properties:
        query:
          type: string
          description: 'Form field: The PromQL query to execute.'
          example: up
        time:
          type: string
          description: 'Form field: The evaluation timestamp (optional, defaults to current time).'
          example: '2023-07-21T20:10:51.781Z'
        limit:
          type: integer
          format: int64
          description: 'Form field: The maximum number of metrics to return.'
          example: 100
        timeout:
          type: string
          description: 'Form field: Evaluation timeout (optional, defaults to and is capped by the value of the -query.timeout flag).'
          example: 30s
        lookback_delta:
          type: string
          description: 'Form field: Override the lookback period for this query (optional).'
          example: 5m

# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/prometheus-io/refs/heads/main/openapi/prometheus-io-query-api-openapi.yml