Skip to main content
POST
Execute

Authorizations

Authorization
string
header
required

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

Prefer
enum<string>

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.

Available options:
respond-async
X-Oleria-Request-Id
string<uuid>

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

application/json
query
string
required

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.

Required string length: 1 - 100000
Example:

"SELECT account_id, mfa_status FROM oleria_account WHERE mfa_status = :status"

model
string
default:oleria_identity

Name of the semantic model to use for query resolution. Defaults to oleria_identity.

Example:

"oleria_identity"

dialect
enum<string>
default:trino

The SQL dialect used for parsing. Currently only trino is supported. Additional dialects may be added in future versions.

Available options:
trino
Example:

"trino"

format
enum<string>
default:json

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.

Available options:
json,
csv
Example:

"csv"

parameters
object

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.

Example:

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.

job_id
string
required

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.

Example:

"athn_a1b2c3d4-e5f6-7890-abcd-ef1234567890"

rows
object[]
required

Query results as an array of records. Each record is a map of column name to value.

statistics
object

Execution statistics for the query. Reported together when the engine returns statistics for an execution; absent when no statistics are available.