Skip to content

Run request query

POST
/v1/requests/{id}/query
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.

id
required
string

Request ID

SQL statement to run

Media typeapplication/json
object
sql
required

SQL is a single read-only statement in DuckDB SQL dialect; see enzoapi.QueryRequest. It is the only field forwarded to env-enzo.

string

Example

SELECT id, email FROM customers WHERE created_at > '2026-01-01' ORDER BY id

Env-enzo response: column order, rows and truncation flag

Media typeapplication/json
object
columns

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.

Array<string>
results

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.

Array<object>
object
key
additional properties
truncated

Truncated is true when more rows were available than the effective limit allowed and the result was cut off at that limit.

boolean

Example

{
"columns": [
"id",
"email"
],
"truncated": false
}

Missing sql (env-manager) or rejected statement (env-enzo, {error})

Media typeapplication/json
object
error
string
message
string
success
boolean

Example

{
"error": "",
"message": "Success",
"success": true
}

Unauthorized

Media typeapplication/json
object
error
string
message
string
success
boolean

Example

{
"error": "",
"message": "Success",
"success": true
}

Not Found

Media typeapplication/json
object
error
string
message
string
success
boolean

Example

{
"error": "",
"message": "Success",
"success": true
}

Request or environment not ready (env-manager) or datasets still loading (env-enzo, {error})

Media typeapplication/json
object
error
string
message
string
success
boolean

Example

{
"error": "",
"message": "Success",
"success": true
}

Internal Server Error

Media typeapplication/json
object
error
string
message
string
success
boolean

Example

{
"error": "",
"message": "Success",
"success": true
}

Enclave unreachable

Media typeapplication/json
object
error
string
message
string
success
boolean

Example

{
"error": "",
"message": "Success",
"success": true
}

Query proxy not available in this deployment mode

Media typeapplication/json
object
error
string
message
string
success
boolean

Example

{
"error": "",
"message": "Success",
"success": true
}