> ## 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. # Instant 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. ## OpenAPI ````yaml /openapi/timeseries.yaml get /api/v1/query 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": , "errorType": "", "error": "", "warnings": [""] } ``` 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: get: summary: Instant query description: | 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. operationId: instantQuery parameters: - name: query in: query required: true description: | 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. schema: type: string example: up{job="node"} - name: time in: query required: false description: | 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. schema: type: string - 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: > 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 content: application/json: schema: $ref: '#/components/schemas/QueryResponse' example: status: success data: resultType: vector result: - metric: __name__: up job: node value: - 1705708800 - '1' '400': description: | Bad request. The PromQL expression could not be parsed, or a required parameter is missing or malformed. 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 (e.g. referencing a non-existent function or type error during evaluation). 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: QueryResponse: type: object description: | Response envelope for an instant query (`/api/v1/query`). On success, `data` contains the query result. On error, `error` and `errorType` describe the failure. properties: status: type: string enum: - success - error data: $ref: '#/components/schemas/QueryResult' 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, such as partial results due to unavailable shards. 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 QueryResult: type: object description: | 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. properties: resultType: type: string enum: - vector - scalar - matrix - string result: description: | Query result. Shape depends on `resultType`: - **vector**: array of `{ metric, value }` objects where `value` is a `[unix_timestamp, "sample_value"]` pair - **matrix**: array of `{ metric, values }` objects where `values` is an array of `[unix_timestamp, "sample_value"]` pairs - **scalar**: `[unix_timestamp, "value"]` pair - **string**: `[unix_timestamp, "string"]` pair Sample values are always strings to support `"NaN"`, `"+Inf"`, and `"-Inf"`. required: - resultType - result ````