Execute a query

NOW=$(date +%s)000000

curl -X POST http://localhost:5080/api/v1/query \
  -H "authorization: Bearer $MS_JWT" \
  -H 'content-type: application/json' \
  -d "{\"org_id\":\"$MS_ORG\",\"language\":\"sql\",
       \"statement\":\"SELECT level, count(*) AS n FROM app GROUP BY level\",
       \"time_range\":{\"start\":$((NOW-3600000000)),\"end\":$((NOW+60000000))},
       \"stream\":{\"name\":\"app\",\"stream_type\":\"logs\"}}"

NOW=$(date +%s)000000

curl -G http://localhost:5080/api/v1/query \
  -H "authorization: Bearer $MS_JWT" \
  --data-urlencode 'language=promql' \
  --data-urlencode 'statement=sum(rate(http_requests_total[5m]))' \
  --data-urlencode "start=$((NOW-3600000000))" \
  --data-urlencode "end=$NOW"

{
  "columns": ["level", "n"],
  "rows": [["error", 12], ["info", 40]],
  "scanned_rows": 10432,
  "took_ms": 18
}

NOW=$(date +%s)000000

curl -X POST http://localhost:5080/api/v1/query \
  -H "authorization: Bearer $MS_JWT" \
  -H 'content-type: application/json' \
  -d "{\"org_id\":\"$MS_ORG\",\"language\":\"sql\",
       \"statement\":\"SELECT level, count(*) AS n FROM app GROUP BY level\",
       \"time_range\":{\"start\":$((NOW-3600000000)),\"end\":$((NOW+60000000))},
       \"stream\":{\"name\":\"app\",\"stream_type\":\"logs\"}}"

NOW=$(date +%s)000000

curl -G http://localhost:5080/api/v1/query \
  -H "authorization: Bearer $MS_JWT" \
  --data-urlencode 'language=promql' \
  --data-urlencode 'statement=sum(rate(http_requests_total[5m]))' \
  --data-urlencode "start=$((NOW-3600000000))" \
  --data-urlencode "end=$NOW"

{
  "columns": ["level", "n"],
  "rows": [["error", 12], ["info", 40]],
  "scanned_rows": 10432,
  "took_ms": 18
}

POST /api/v1/query
GET  /api/v1/query

Runs a query and returns the rows, or starts an asynchronous search job for a large query. The call requires streams.query, or sys.telemetry.read for system telemetry. Body

Field	Type	Required	Notes
`org_id`	string	Yes	Must be present, and the value is ignored. The authenticated organization applies.
`language`	string	Yes	`sql` or `promql`.
`statement`	string	Yes	The query text.
`time_range`	object	Yes	`{ "start": <microseconds>, "end": <microseconds> }`.
`stream`	object	For SQL	`{ "name": "app", "stream_type": "logs" }` names the primary table. Both fields are required, and the type is `logs`, `metrics`, `traces`, `profiles`, or `extend`.
`limit`	integer	No	Row cap.

Query string of a GET GET /api/v1/query takes the same query in its query string, so a read is an address that can be copied and opened again. It answers as the POST does, honours the same headers, and needs the same permission. Send a statement too long for an address as a POST: a proxy in front of the server may refuse a request line longer than 8 KB.

Parameter	Required	Notes
`language`	Yes	`sql` or `promql`.
`statement`	Yes	The query text, URL-encoded.
`start`, `end`	Yes	The time range in microseconds.
`stream`, `stream_type`	For SQL	The primary table and its type, given together.
`limit`	No	Row cap.

Headers and query string

Name	Effect
`Prefer: respond-async`	Always creates a search job and answers `202`.
`Prefer: respond-sync`	Runs in the request even for a long range.
`Accept: application/x-ndjson`	Streams one JSON object per row, then a `{"__meta__": ...}` record.
`?clusters=local,remote`	Includes remote clusters in a federated search.

NOW=$(date +%s)000000

curl -X POST http://localhost:5080/api/v1/query \
  -H "authorization: Bearer $MS_JWT" \
  -H 'content-type: application/json' \
  -d "{\"org_id\":\"$MS_ORG\",\"language\":\"sql\",
       \"statement\":\"SELECT level, count(*) AS n FROM app GROUP BY level\",
       \"time_range\":{\"start\":$((NOW-3600000000)),\"end\":$((NOW+60000000))},
       \"stream\":{\"name\":\"app\",\"stream_type\":\"logs\"}}"

NOW=$(date +%s)000000

curl -G http://localhost:5080/api/v1/query \
  -H "authorization: Bearer $MS_JWT" \
  --data-urlencode 'language=promql' \
  --data-urlencode 'statement=sum(rate(http_requests_total[5m]))' \
  --data-urlencode "start=$((NOW-3600000000))" \
  --data-urlencode "end=$NOW"

{
  "columns": ["level", "n"],
  "rows": [["error", 12], ["info", 40]],
  "scanned_rows": 10432,
  "took_ms": 18
}

A query whose estimated size reaches [querier].auto_async_threshold_rows answers 202:

{
  "job_id": "3KE1WD4SrFXhyftdMJY0FN7fTFj",
  "monitor": "/api/v1/query/jobs/3KE1WD4SrFXhyftdMJY0FN7fTFj",
  "state": "pending"
}

See Query for the thresholds and the job endpoints. Errors

Status	Cause
`400`	The statement cannot be planned, the `stream` hint is missing for SQL (`query.stream hint is required`), or the query would read more rows than `[querier].max_scan_rows` allows. A `GET` also answers `400` when a required parameter is missing or `stream` comes without `stream_type`.
`503`	In a role-split cluster, no `querier` node is alive (`no querier node is available`).
`403`	The stream does not exist in the organization (`stream not found: <name>`), or the token lacks `streams.query`.
`422`	A body field is missing or has the wrong type, for example `org_id` or `stream_type`. The response is plain text.

Last modified on October 26, 2026

Overview

Authentication

Intake

Query

APM

RUM

Streams

Alerting

Correlation & Web

Platform & Administration