Run a read-only SQL query
const url = 'https://example.com/api/query/';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"sql":"example","restrict_tables":["example"],"row_limit":100}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/api/query/ \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "sql": "example", "restrict_tables": [ "example" ], "row_limit": 100 }'Execute one SELECT through the read-only SQL sandbox.
The statement must be a single SELECT over data.* tables you can
access, name every table in restrict_tables, and fit the sandbox’s
function allowlist and cost bounds. Rows are capped by row_limit,
execution by a server-side statement timeout, and the result’s size before
it leaves the database: truncated is true when either cap cut rows. A
result whose first row alone exceeds the size cap, or whose response would
exceed 8 MiB, is refused with 422.
Authorizations
Section titled “ Authorizations ”Request Bodyrequired
Section titled “ Request Bodyrequired ”One read-only SELECT plus its mandatory table scope.
object
A single SELECT statement over data.* tables.
Table names (without the data. prefix) the query may touch. Required and non-empty; intersected with your access — it can only narrow what you already see, never widen it.
Maximum rows to return.
Responses
Section titled “ Responses ”Successful Response
Structured result from sandbox query execution.
Uses list-of-lists for rows (not list-of-dicts) for serialization performance.
object
Example generated
{ "rows": [ [ "example" ] ], "columns": [ "example" ], "row_count": 1, "truncated": true}Bad request — invalid query parameters or payload
object
A machine-readable code for the problem, on the errors that carry one, such as catalog_lock_conflict on a 409 for a row another request holds. Absent otherwise.
The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.
The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.
object
Example
{ "detail": "Dataset not found", "status": 404, "title": "Not Found", "type": "about:blank"}Unauthorized — missing or invalid credentials
object
A machine-readable code for the problem, on the errors that carry one, such as catalog_lock_conflict on a 409 for a row another request holds. Absent otherwise.
The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.
The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.
object
Example
{ "detail": "Dataset not found", "status": 404, "title": "Not Found", "type": "about:blank"}Forbidden — caller lacks access to this resource
object
A machine-readable code for the problem, on the errors that carry one, such as catalog_lock_conflict on a 409 for a row another request holds. Absent otherwise.
The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.
The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.
object
Example
{ "detail": "Dataset not found", "status": 404, "title": "Not Found", "type": "about:blank"}Not found
object
A machine-readable code for the problem, on the errors that carry one, such as catalog_lock_conflict on a 409 for a row another request holds. Absent otherwise.
The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.
The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.
object
Example
{ "detail": "Dataset not found", "status": 404, "title": "Not Found", "type": "about:blank"}Validation error
object
A machine-readable code for the problem, on the errors that carry one, such as catalog_lock_conflict on a 409 for a row another request holds. Absent otherwise.
The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.
The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.
object
Example
{ "detail": "Dataset not found", "status": 404, "title": "Not Found", "type": "about:blank"}Too many requests — retry after the advertised interval
object
A machine-readable code for the problem, on the errors that carry one, such as catalog_lock_conflict on a 409 for a row another request holds. Absent otherwise.
The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.
The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.
object
Example
{ "detail": "Dataset not found", "status": 404, "title": "Not Found", "type": "about:blank"}Headers
Section titled “ Headers ”Seconds until the request may be retried
Internal server error
object
A machine-readable code for the problem, on the errors that carry one, such as catalog_lock_conflict on a 409 for a row another request holds. Absent otherwise.
The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.
The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.
object
Example
{ "detail": "Dataset not found", "status": 404, "title": "Not Found", "type": "about:blank"}Service unavailable — the database could not serve the request
object
A machine-readable code for the problem, on the errors that carry one, such as catalog_lock_conflict on a 409 for a row another request holds. Absent otherwise.
The refused change, on a dataset_in_shared_maps 422: unpublish, restrict_visibility or delete. Absent otherwise.
The shared maps behind a dataset_in_shared_maps 422, as {"id", "name"} pairs. Absent otherwise.
object
Example
{ "detail": "Dataset not found", "status": 404, "title": "Not Found", "type": "about:blank"}