v4

latestOpenAPI 3.1.02026-08-01207318738.7 KB

Query

Execute a semantic query

Runs a semantic query. By default (no resultType) the response is a stream of newline-delimited JSON (Content-Type: text/ndjson), one JSON object per line: a jobs_submitted header, then one line per job as it reaches a terminal state (a completed job carries the result set as base64-encoded Arrow IPC in result; use summary.fields to interpret the decoded columns), then a footer. A footer with non-empty remaining_job_ids means the wait window elapsed before every job finished — poll GET /api/v1/query/wait with those IDs until the list is empty. When resultType is set, the response is instead a single CSV, XLSX, or JSON document, and a timeout is reported as a 408.

post/api/v1/query/run

Query parameters

userIdstring uuid

Target user membership ID (for org-scoped API keys)

Request body

branchIdstring uuid

Optional model branch to run the query against. Must belong to the same shared model as the query. When omitted, the query runs against the shared model. Takes precedence over the legacy ?branch_id= URL query parameter.

cache'disabled' | 'normal' | 'refresh' | 'refresh_all'

Cache policy for query execution. Controls whether to use cached results.

environmentConnectionIdstring uuid

Connection ID of the environment to run the query against, overriding the connection environment inherited from the (target) user's session or default. Must be a configured environment of the query model's connection that the user can access.

formatResultsboolean

Whether to format result values (e.g., apply number formatting). Only valid when resultType is specified.

planOnlyboolean

If true, returns only the query execution plan without running the query.

{"stackTrail":"components:schemas:QueryRunBody:properties:query","oasType":"schema","type":"unknown","description":"The semantic query definition including fields, filters, sorts, and other query parameters."}

resultType'csv' | 'json' | 'xlsx'

Output format for the results. If not specified, returns base64-encoded Arrow format.

userIdstring uuid

Alternate location for the ?userId= query parameter. Prefer the query parameter — this body field exists for backwards compatibility. Supplying both forms results in a 400. Only valid for org-scoped API keys; when set, the user's attributes are applied for row-level security and connection-environment switching.

workbookUrlboolean

If true, creates an ephemeral workbook for the query and returns its URL in the X-Omni-Workbook-Url response header, for all resultType modes. Requires the workbooks permission on the query's model for the (target) user; the header is silently omitted otherwise. Cannot be combined with planOnly.

Example request

{
  "branchId": "550e8400-e29b-41d4-a716-446655440000",
  "cache": "normal",
  "environmentConnectionId": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "550e8400-e29b-41d4-a716-446655440000"
}

Response

Query executed or started successfully. The default response (no resultType) is a text/ndjson stream — one JSON object per line, each matching QueryRunStreamLine; it cannot be parsed as a single JSON document. When resultType is set, the body is a single CSV, XLSX, or JSON document instead.

object[] required

Array of result-row objects keyed by field name. Returned only when resultType is "json".