Run request query
const url = 'https://localhost:8080/v1/requests/example/query';const options = { method: 'POST', headers: {Authorization: '<Authorization>', 'Content-Type': 'application/json'}, body: '{"sql":"SELECT id, email FROM customers WHERE created_at > \'2026-01-01\' ORDER BY id"}'};
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://localhost:8080/v1/requests/example/query \ --header 'Authorization: <Authorization>' \ --header 'Content-Type: application/json' \ --data '{ "sql": "SELECT id, email FROM customers WHERE created_at > '\''2026-01-01'\'' ORDER BY id" }'Runs a read-only SQL statement against the enclave of an active request. This is the customer-facing route to env-enzo’s POST /v1/query/run: env-manager checks the caller owns the request (or is an org admin), that the request is active and its environment ready, then forwards {"sql": ...} to the sidecar and returns its response verbatim. Only sql is forwarded; the sidecar’s limit field is not accepted here, so results are capped at 10000 rows (truncated: true when the cap hit). Use the tunnel edge to pass a limit.
SQL is DuckDB dialect over tables named by the relation names listed in GET /v1/requests/{id}/status. Statements starting with INSERT, UPDATE, DELETE, DROP, CREATE, ALTER, TRUNCATE, REPLACE or MERGE are rejected.
Errors raised by env-manager before the query reaches the enclave use the {success, message, error} shape: 400 (missing sql), 401, 404 (not your request), 409 (request not active, no environment yet, or environment not ready), 502 (enclave unreachable), 503 (query proxy unavailable in this deployment). Errors raised by env-enzo are passed through with its {"error": "..."} shape: 400 for a write statement or a DuckDB parser/binder/catalog error, 409 while the datasets are still loading (poll the status endpoint until ready), 500 for an execution failure.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Request ID
Request Body
Section titled “Request Body”SQL statement to run
object
SQL is a single read-only statement in DuckDB SQL dialect; see enzoapi.QueryRequest. It is the only field forwarded to env-enzo.
Example
SELECT id, email FROM customers WHERE created_at > '2026-01-01' ORDER BY idResponses
Section titled “Responses”Env-enzo response: column order, rows and truncation flag
object
Columns are the result column names in SELECT order. The row objects in results are JSON objects whose keys are serialised alphabetically, so this list is the only place the query’s column order survives.
Results holds one object per row, keyed by column name. DuckDB values map to their natural JSON type (numbers, strings, booleans, null); timestamps and dates are RFC 3339 strings and INTERVAL values are rendered as DuckDB prints them (e.g. “1 year 2 days 04:05:06”). Empty when the query matched no rows.
object
Truncated is true when more rows were available than the effective limit allowed and the result was cut off at that limit.
Example
{ "columns": [ "id", "email" ], "truncated": false}Missing sql (env-manager) or rejected statement (env-enzo, {error})
object
Example
{ "error": "", "message": "Success", "success": true}Unauthorized
object
Example
{ "error": "", "message": "Success", "success": true}Not Found
object
Example
{ "error": "", "message": "Success", "success": true}Request or environment not ready (env-manager) or datasets still loading (env-enzo, {error})
object
Example
{ "error": "", "message": "Success", "success": true}Internal Server Error
object
Example
{ "error": "", "message": "Success", "success": true}Enclave unreachable
object
Example
{ "error": "", "message": "Success", "success": true}Query proxy not available in this deployment mode
object
Example
{ "error": "", "message": "Success", "success": true}