> ## Documentation Index
> Fetch the complete documentation index at: https://docs.molesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Execute a query

> Run SQL or PromQL against an organization-scoped telemetry stream.

```http theme={null}
POST /api/v1/query
```

**Body**

| Field        | Type    | Required | Notes                                                                                      |
| ------------ | ------- | -------- | ------------------------------------------------------------------------------------------ |
| `org_id`     | string  | ✅        | Kept for request compatibility; the authenticated organization is authoritative.           |
| `language`   | string  | ✅        | `sql` or `promql`.                                                                         |
| `statement`  | string  | ✅        | Query text.                                                                                |
| `time_range` | object  | ✅        | `{ "start": <microseconds>, "end": <microseconds> }` — microseconds.                       |
| `stream`     | object  | —        | `{ "name", "stream_type" }`; type is `logs`, `metrics`, `traces`, `profiles`, or `extend`. |
| `limit`      | integer | —        | Row cap.                                                                                   |

Execution requires `streams.query`; system telemetry queries may use `sys.telemetry.read`. Send
`Accept: application/x-ndjson` to return one object per row followed by a `__meta__` record. Send
`Prefer: respond-async` to receive a `202` search job instead. Enterprise Edition can add
`?clusters=local,remote-name` for federated search.

<RequestExample>
  ```bash cURL theme={null}
  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(*) FROM app GROUP BY level\",
         \"time_range\":{\"start\":0,\"end\":2000000000000000},
         \"stream\":{\"name\":\"app\",\"stream_type\":\"logs\"}}"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "columns": ["level", "count"],
    "rows": [["error", 12]],
    "scanned_rows": 10432,
    "took_ms": 18
  }
  ```
</ResponseExample>