Run SQL and get rows back.
Send either sql (free-form) or query_id (a saved query to execute); if
both are present sql wins and query_id is recorded only as the run’s
origin. params is a JSON array of positional values substituted for
$1…$N in the statement.
Results are scoped to your organization no matter how the SQL is written — there is no way to phrase a query that reads another organization’s data.
One read-only statement is accepted and nothing else:
- it must start with
SELECTorWITH; - a
;outside a string literal is rejected — no multi-statement bodies; - 8000 characters maximum;
- a single statement may not join the analytics tables (
events,evaluations,agent_sessions) to the operational ones (dashboards,saved_queries,api_keys,users, …) — split it into two queries.
Use GET /queries/schema for the tables and columns you can read.
A successful run returns {columns, rows, truncated, elapsed_ms}, where
each entry in rows is an array of values positionally matching columns.
At most 10 000 rows come back; truncated is true when there were more,
so page with LIMIT/OFFSET in your own SQL rather than relying on the
cap. A run is cut off after 10 seconds.
A NUMERIC column comes back as null — cast it in the SELECT
(avg(x)::float8).
Every run, including a rejected or failed one, is recorded in the query audit log with its SQL, parameters, duration and outcome.
Authorizations
Body
Response
columns, rows, truncated and elapsed_ms.

