# Queries API

> Compile and run semantic-model queries, batch several at once, and inspect the compiled SQL — all under /api/query.

*[View this page in the Flax docs](https://flax-analytics.com/docs/api-reference/queries)*

The queries endpoints compile a semantic-model query to dialect-correct SQL, run it
in your warehouse, and return rows. They require the `read` scope.

## Run a query

`POST /api/query` — compile and run one query.

```bash
curl https://flax-analytics.com/api/query \
  -H "Authorization: Bearer flax_pat_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "orders",
    "dimensions": ["orders.status"],
    "measures": ["orders.revenue"],
    "filters": [{ "field": "orders.created_at", "op": ">=", "value": "2026-01-01" }],
    "orderBy": ["orders.revenue desc"],
    "limit": 100
  }'
```

The response contains typed `columns` and `rows`:

```json
{
  "columns": [
    { "name": "orders.status", "type": "string" },
    { "name": "orders.revenue", "type": "number" }
  ],
  "rows": [["completed", 128400.5], ["pending", 9120.0]]
}
```

## Run several queries

`POST /api/query/batch` — run multiple queries in one round-trip. The response
returns one result per query, in request order. Prefer this over many single calls.

## Inspect a compiled query

`POST /api/query/detail` — return the compiled SQL and dialect for a query
**without running it**. Useful for debugging the semantic layer.

```json
{ "sql": "SELECT status, SUM(amount) ...", "dialect": "snowflake" }
```

## Related

- [Building queries in the UI](/docs/exploring/building-queries)
- [SQL compilation](/docs/modeling/sql-compilation)
- [Errors & limits](/docs/api-reference/errors-and-limits)