---
title: "Instant query"
method: GET
path: "/api/v1/query"
---

# Instant query

`GET /api/v1/query`

Evaluate a PromQL expression at a single point in time.

The result can be a vector (set of instant samples), a scalar, a
string, or even a matrix depending on the expression type. The
`resultType` field in the response indicates the shape of the
`result` array.

If `time` is omitted the server uses the current server time.
Also accepts POST with a `application/x-www-form-urlencoded` body
containing the same parameters.

## Query parameters

- `query` string, required
- `time` string
- `timeout` string

## Response `200`

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

- QueryResponse — 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` 'success' | 'error', required
  - `data` QueryResult — 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.
    - `resultType` 'vector' | 'scalar' | 'matrix' | 'string', required
    - `result` unknown, required
  - `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`.

## Other responses

- `400` — Bad request. The PromQL expression could not be parsed, or a required parameter is missing or malformed. The `errorType` will be `bad_data`.
- `422` — Unprocessable Entity. The expression is syntactically valid but could not be executed (e.g. referencing a non-existent function or type error during evaluation). 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` — 2 info
  - added the non-success response with the status `422`
  - added the optional property `warnings` to the response with the `200` status

[Change history](https://skmtc.dev/opendata-oss/apis/opendata-timeseries-api/changes/api/v1/query/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)