Skip to main content
GET
/
api
/
v1
/
query
Instant query
curl --request GET \
  --url http://localhost:9090/api/v1/query
{
  "status": "success",
  "data": {
    "resultType": "vector",
    "result": [
      {
        "metric": {
          "__name__": "up",
          "job": "node"
        },
        "value": [
          1705708800,
          "1"
        ]
      }
    ]
  }
}

Query Parameters

​
query
string
required

PromQL expression to evaluate. This can be any valid PromQL expression including selectors (up{job="node"}), functions (rate(http_requests_total[5m])), aggregations (sum by (job) (up)), or arithmetic.

​
time
string

Evaluation timestamp — the point in time at which the expression is evaluated. Accepts RFC 3339 (e.g. 2024-01-20T00:00:00Z) or Unix seconds with optional decimal precision (e.g. 1705708800 or 1705708800.123). Defaults to current server time when omitted.

​
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

Successful query result. The data.resultType field indicates the shape of data.result:

  • vector: array of { metric, value } objects (most common for instant queries)
  • scalar: a single [timestamp, "value"] pair
  • matrix: array of { metric, values } objects
  • string: a single [timestamp, "string"] pair

Response envelope for an instant query (/api/v1/query). On success, data contains the query result. On error, error and errorType describe the failure.

​
status
enum<string>
required
Available options:
success,
error
​
data
object

Result payload for an instant query. The resultType indicates the shape of result:

  • vector: An array of { metric, value } objects — one per matching time series. This is the most common result type for instant queries on selectors and functions.
  • matrix: An array of { metric, values } objects — returned when the expression produces a range vector (e.g. using a subquery).
  • scalar: A single [timestamp, "value"] pair — returned for pure numeric expressions like 1 + 1.
  • string: A single [timestamp, "string"] pair — returned for string literals.
​
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, such as partial results due to unavailable shards. May be present even when status is success.