Execute
Validates and executes the SQL query. If the query completes within the server-side sync threshold, the response is 200 with inline rows. If not, the response is 202 with a job_id for polling. Clients must always handle both 200 and 202.
Both responses carry a job_id; pass it to GET /v1/query/jobs/{job_id} to obtain a download URL for the result file — the same path for synchronous and asynchronous results.
Setting Prefer: respond-async (RFC 7240) skips the sync threshold and returns 202 immediately.
Idempotency: The optional X-Oleria-Request-Id header is used as the execution idempotency key — see the parameter description for semantics and constraints.
Authorizations
OAuth 2.0 Client Credentials flow. The tokenUrl shown is for the production environment. For other environments, replace prod with the target environment name (e.g., auth.staging.oleria.io for staging).
Headers
Set to respond-async to request asynchronous execution (RFC 7240, Section 4.1). The response will return immediately with a job_id and status: pending.
respond-async Correlation ID and execution idempotency key. Must be a canonical 36-char hyphenated UUID, case-insensitive (e.g., 3bce7950-12a5-4b70-aeb9-270f1a9dec6e). Sending the same UUID on a retry returns the original execution rather than starting a duplicate. When omitted, the server generates a UUID for the request — safe, but the caller has no way to retry idempotently. A header value that is not a valid UUID is rejected with 400.
Body
The query string to validate and/or execute. Queries above the maximum length are rejected before parsing; real-world queries sit well below the bound.
1 - 100000"SELECT account_id, mfa_status FROM oleria_account WHERE mfa_status = :status"
Name of the semantic model to use for query resolution. Defaults to oleria_identity.
"oleria_identity"
The SQL dialect used for parsing. Currently only trino is supported. Additional dialects may be added in future versions.
trino "trino"
Result format of the downloadable file, fixed at submission. json (default) delivers large results as JSON Lines (NDJSON); best for programmatic and AI consumers. csv produces a single comma-separated file with a header row and renders every value as text; best for spreadsheet export and tabular UIs. The inline rows preview is JSON either way (scalar values keep their type). Ignored by /v1/query/validate, which does not execute.
json, csv "csv"
Named parameter values for query placeholders. Use :name syntax in the SQL query (e.g., :status, :created_after). Parameter names must match exactly (case-sensitive). Type coercion is automatic: strings are quoted, numbers and booleans are used as-is.
Response
Query executed successfully within the sync threshold. Contains inline rows and execution statistics.
Synchronous query result: the complete row set inline plus a job identifier for downloading the same result as a file. Column types can be obtained from the semantic model.
Identifier for this execution. rows already holds the complete result (bounded by the row-limit policy); pass this id to GET /v1/query/jobs/{job_id} to download the same result as a file without re-running the query.
"athn_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
Query results as an array of records. Each record is a map of column name to value.
Execution statistics for the query. Reported together when the engine returns statistics for an execution; absent when no statistics are available.

