Skip to main content
GET
/
api
/
v1
/
query_range
Range query
curl --request GET \
  --url http://localhost:9090/api/v1/query_range
{
  "status": "success",
  "data": {
    "resultType": "matrix",
    "result": [
      {
        "metric": {
          "__name__": "http_requests_total",
          "method": "GET"
        },
        "values": [
          [
            1705708800,
            "10"
          ],
          [
            1705708815,
            "12"
          ]
        ]
      }
    ]
  }
}

Query Parameters

​
query
string
required

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.

​
start
string
required

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).

​
end
string
required

End timestamp (inclusive) of the evaluation range. Accepts RFC 3339 or Unix seconds. Must be greater than or equal to start.

​
step
string
required

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.

​
timeout
string

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.

Response

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.

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
enum<string>
required
Available options:
success,
error
​
data
object

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.

​
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.