---
title: "Range query"
method: GET
path: "/api/v1/query_range"
---

# Range query

`GET /api/v1/query_range`

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.

## Query parameters

- `query` string, required
- `start` string, required
- `end` string, required
- `step` string, required
- `timeout` string

## Response `200`

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.

- QueryRangeResponse — 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.
  - `status` 'success' | 'error', required
  - `data` QueryRangeResult — 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`.
    - `resultType` 'matrix', required
    - `result` MatrixSeries[], required
      - `metric` object, required — Label set identifying the series. Keys are label names, values are label values. The `__name__` label contains the metric name.
      - `values` array[], required — 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.
        - unknown[]
          - unknown
  - `error` string — Human-readable error message (present when status is `error`).
  - `errorType` string — Error category (present when status is `error`): `bad_data`, `internal`, or `unavailable`.
  - `warnings` string[] — Non-fatal warnings from the query engine. May be present even when `status` is `success`.

## Other responses

- `400` — 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`.
- `422` — Unprocessable Entity. The expression is syntactically valid but could not be executed. The `errorType` will be `bad_data`.
- `500` — Internal server error. The `errorType` will be `internal`.
- `503` — Service unavailable. Returned when the query times out or the server is under backpressure. The `errorType` will be `unavailable`.

## Changes

- **2026-02-12** `6e511aad037c` — 1 breaking, 3 info
  - added `subschema #1, subschema #2` to the `data/result/items/values/items/` response property 'prefixItems' list for the response status `200`
  - added the non-success response with the status `422`
  - added the optional property `warnings` to the response with the `200` status
  - removed `subschema #1, subschema #2` from the `data/result/items/values/items/` response property 'prefixItems' list for the response status `200`

[Change history](https://skmtc.dev/opendata-oss/apis/opendata-timeseries-api/changes/api/v1/query_range/get.md)

---

[API](https://skmtc.dev/opendata-oss/apis/opendata-timeseries-api.md) · [All operations](https://skmtc.dev/opendata-oss/apis/opendata-timeseries-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/opendata-oss/opendata-timeseries-api/revisions/6e511aad037c/schema)