> ## Documentation Index
> Fetch the complete documentation index at: https://opendata.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Range query

> Evaluate a PromQL expression over a range of time, returning a matrix
of time series with regularly spaced samples.

The expression is evaluated at each `step` interval between `start`
and `end` (both inclusive). The result is always a matrix
(`resultType: "matrix"`), where each series contains an array of
`[timestamp, value]` pairs spaced by `step`.

Also accepts POST with a `application/x-www-form-urlencoded` body
containing the same parameters.




## OpenAPI

````yaml /openapi/timeseries.yaml get /api/v1/query_range
openapi: 3.1.0
info:
  title: OpenData Timeseries API
  version: 1.0.0
  description: |
    Prometheus-compatible HTTP API for the OpenData Timeseries service.

    Query endpoints accept both GET (query parameters) and POST
    (application/x-www-form-urlencoded body) with identical parameters.
    This spec documents the GET form; POST is always available as an
    alternative for large queries that may exceed URL character limits.

    ## Timestamp formats

    All timestamp parameters accept either **RFC 3339** format
    (e.g. `2024-01-20T00:00:00Z`) or **Unix seconds** as a float
    (e.g. `1705708800` or `1705708800.123`). Timestamps in responses are
    always Unix seconds.

    ## Duration format

    Duration parameters use PromQL duration syntax: an integer followed by a
    unit suffix. Supported units are `ms` (milliseconds), `s` (seconds),
    `m` (minutes), `h` (hours), `d` (days), `w` (weeks), and `y` (years).
    Examples: `30s`, `5m`, `1h30m`.

    ## Sample values

    Sample values are always transferred as JSON strings (not numbers) to
    allow special values such as `"NaN"`, `"+Inf"`, and `"-Inf"`.

    ## Response envelope

    Every JSON response follows a common envelope:
    ```json
    {
      "status": "success" | "error",
      "data": <payload>,
      "errorType": "<string>",
      "error": "<string>",
      "warnings": ["<string>"]
    }
    ```
    The `error` and `errorType` fields are only present when `status` is
    `"error"`. The `warnings` array may be present on successful responses
    when the query engine has non-fatal issues to report (e.g. partial
    results due to unavailable shards).
servers:
  - url: http://localhost:9090
    description: Local development server
security: []
paths:
  /api/v1/query_range:
    get:
      summary: Range query
      description: |
        Evaluate a PromQL expression over a range of time, returning a matrix
        of time series with regularly spaced samples.

        The expression is evaluated at each `step` interval between `start`
        and `end` (both inclusive). The result is always a matrix
        (`resultType: "matrix"`), where each series contains an array of
        `[timestamp, value]` pairs spaced by `step`.

        Also accepts POST with a `application/x-www-form-urlencoded` body
        containing the same parameters.
      operationId: rangeQuery
      parameters:
        - name: query
          in: query
          required: true
          description: |
            PromQL expression to evaluate at each step. Typically a
            rate or aggregation function (e.g. `rate(http_requests_total[5m])`),
            but any valid PromQL expression is accepted.
          schema:
            type: string
          example: rate(http_requests_total[5m])
        - name: start
          in: query
          required: true
          description: |
            Start timestamp (inclusive) of the evaluation range. Accepts
            RFC 3339 (e.g. `2024-01-20T00:00:00Z`) or Unix seconds with
            optional decimal precision (e.g. `1705708800`).
          schema:
            type: string
          example: '2024-01-20T00:00:00Z'
        - name: end
          in: query
          required: true
          description: |
            End timestamp (inclusive) of the evaluation range. Accepts
            RFC 3339 or Unix seconds. Must be greater than or equal to
            `start`.
          schema:
            type: string
          example: '2024-01-20T01:00:00Z'
        - name: step
          in: query
          required: true
          description: |
            Query resolution step width — the interval between consecutive
            evaluation points. Can be a duration string (e.g. `15s`, `1m`)
            or a float number of seconds (e.g. `15`, `60.0`). Smaller steps
            produce more data points but increase query cost.
          schema:
            type: string
          example: 15s
        - name: timeout
          in: query
          required: false
          description: |
            Evaluation timeout. If the query does not complete within this
            duration, it is aborted and a 503 error is returned. Duration
            string such as `30s`, `1m`, or `2h`. The server may cap this
            value with its own configured maximum.
          schema:
            type: string
      responses:
        '200':
          description: |
            Range query result. Always returns `resultType: "matrix"` with
            an array of time series, each containing regularly spaced
            `[timestamp, value]` pairs. Series are sorted by their metric
            label set.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryRangeResponse'
              example:
                status: success
                data:
                  resultType: matrix
                  result:
                    - metric:
                        __name__: http_requests_total
                        method: GET
                      values:
                        - - 1705708800
                          - '10'
                        - - 1705708815
                          - '12'
        '400':
          description: |
            Bad request. The PromQL expression could not be parsed, a
            required parameter is missing or malformed, or `end` is before
            `start`. The `errorType` will be `bad_data`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: |
            Unprocessable Entity. The expression is syntactically valid but
            could not be executed. The `errorType` will be `bad_data`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error. The `errorType` will be `internal`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: |
            Service unavailable. Returned when the query times out or the
            server is under backpressure. The `errorType` will be
            `unavailable`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    QueryRangeResponse:
      type: object
      description: |
        Response envelope for a range query (`/api/v1/query_range`). On
        success, `data` always contains a matrix result. On error, `error`
        and `errorType` describe the failure.
      properties:
        status:
          type: string
          enum:
            - success
            - error
        data:
          $ref: '#/components/schemas/QueryRangeResult'
        error:
          type: string
          description: Human-readable error message (present when status is `error`).
        errorType:
          type: string
          description: |
            Error category (present when status is `error`):
            `bad_data`, `internal`, or `unavailable`.
        warnings:
          type: array
          items:
            type: string
          description: |
            Non-fatal warnings from the query engine. May be present even
            when `status` is `success`.
      required:
        - status
    ErrorResponse:
      type: object
      description: |
        Prometheus-compatible error response. Returned for all non-2xx
        responses. The `errorType` indicates the category:

        - `bad_data` (HTTP 400/422): The request was malformed or the
          expression could not be executed.
        - `internal` (HTTP 500): An unexpected server-side error occurred.
        - `unavailable` (HTTP 503): The server is temporarily unable to
          handle the request due to backpressure or a query timeout.
      properties:
        status:
          type: string
          example: error
        errorType:
          type: string
          description: |
            Error category. Maps to HTTP status codes:
            - `bad_data` → 400 or 422
            - `internal` → 500
            - `unavailable` → 503
          enum:
            - bad_data
            - internal
            - unavailable
        error:
          type: string
          description: Human-readable error message describing what went wrong.
      required:
        - status
        - errorType
        - error
    QueryRangeResult:
      type: object
      description: |
        Result payload for a range query. The `resultType` is always
        `"matrix"`. Each element in `result` is a time series containing
        regularly spaced samples between the requested `start` and `end`.
      properties:
        resultType:
          type: string
          enum:
            - matrix
        result:
          type: array
          items:
            $ref: '#/components/schemas/MatrixSeries'
      required:
        - resultType
        - result
    MatrixSeries:
      type: object
      description: |
        A single time series in a matrix result. Contains the full label set
        identifying the series and an array of timestamp/value sample pairs
        ordered chronologically.
      properties:
        metric:
          type: object
          additionalProperties:
            type: string
          description: |
            Label set identifying the series. Keys are label names, values
            are label values. The `__name__` label contains the metric name.
        values:
          type: array
          items:
            type: array
            prefixItems:
              - type: number
                description: Unix timestamp in seconds (epoch time).
              - type: string
                description: |
                  Sample value as a string. String encoding allows special
                  values: `"NaN"`, `"+Inf"`, `"-Inf"`.
            minItems: 2
            maxItems: 2
          description: |
            Chronologically ordered array of `[timestamp, value]` pairs.
            For range queries, pairs are spaced at the requested `step`
            interval. Gaps may appear if no sample was found within the
            lookback window at a given evaluation step.
      required:
        - metric
        - values

````