Run query
Run the semantic query specified in the request body. Successful requests will return the results according to the specified resultType.
Specifying result types
TheresultType parameter determines how the API returns query results:
- When set, the response is a single CSV, XLSX, or JSON document.
-
When not set, the response is a stream of newline-delimited JSON, one JSON object per line: a
jobs_submittedheader, then one line per job as it reaches a terminal state. A completed job contains the result set as base64-encoded Arrow IPC inresult; usesummary.fieldsto interpret the decoded columns. The response will also contain afooter. A footer with non-emptyremaining_job_idsmeans the wait window elapsed before every job finished. See Timeouts below for more information.
Timeouts
If a request takes too long, the API will return a408 timeout error with a remaining_job_ids property. When this occurs, poll the Wait for query results endpoint until the timed_out property is false.Authorizations
Can be either an Organization API Key or Personal Access Token (PAT).
Include in the Authorization header as: Bearer YOUR_TOKEN
Query Parameters
Requires an Organization API key. The ID of the user to run the query as. Prefer using this parameter to specify a user over the userId request body parameter.
If not provided as a query parameter or in the request body, the API runs the query as the calling user.
Personal Access Tokens (PATs) cannot use this parameter to act on behalf of other users.
Body
A JSON object representing the query to be run.
To retrieve a query's JSON object from an Omni workbook:
- Open a workbook in Omni.
- Click the bug icon to toggle open the Inspector panel. For Mac use
Option + 9; for Windows, useAlt + 9. - Locate the Query structure section.
- Copy the query JSON.
Optional ID of a model branch to execute the query against. When provided, the query runs against the specified branch instead of the shared model.
The branch must belong to the same shared model specified in query.modelId and be within your organization.
Takes precedence over the legacy ?branch_id= URL query parameter.
Connection ID of the environment to run the query against, overriding the connection environment inherited from the calling user's (or target user, if userId is provided) session or default. The requesting user must have access to the specified environment.
Prefer passing userId as a query parameter instead of in the request body. Providing userId in both locations will return a 400 error.
Requires an Organization API key. Executes the query as the specified user. When set, the user's attributes are applied for row-level security and connection-environment switching. The userId must belong to a user in your organization.
If not provided as a query parameter or in the request body, the API uses the user associated with the API token.
Cache policy to control how query caching behaves. Must be one of:
Standard- Uses standard caching behavior.SkipRequery- Default. Uses cached results if available, but does not requery if not found.SkipCache- Bypasses cache and always executes a fresh query.SkipCacheAndRebuildExtracts- Same asSkipCache, and also rebuilds any extracts the query depends on.
Standard, SkipRequery, SkipCache, SkipCacheAndRebuildExtracts Cannot be used with planOnly. Specifies the format of query results exported by the API.
If omitted, the response is a stream of newline-delimited JSON. See Specifying result types for more information.
For csv and xlsx, if the query has subtotal or grand total rows, one dimension cell in each totals row is labeled Total. This doesn't apply to the base-64 encoded format or json.
csv, json, xlsx Cannot be used with resultType. If true, returns only the query execution plan without running the query. The response will include the generated SQL and query metadata.
Applicable only if resultType is specified. If true, formatting will be applied to numeric and currency values in the form of currency symbols and thousand separators.
IANA timezone identifier, such as America/Los_Angeles, that overrides the user's configured timezone for this query. Only takes effect when the connection has user-specific timezones enabled.
Cannot be combined with planOnly. If true, creates an ephemeral workbook reproducing the query (preserving the run's branchId and timezone) and returns its URL in the X-Omni-Workbook-Url response header. The header works for all resultType modes and is delivered as a header to keep response bodies byte-identical.
The header is best-effort: it will be silently omitted if the (target) user lacks the workbooks permission (USE_WORKBOOKS) on the query's model, or if workbook creation fails.
Response
Query executed or started successfully. The result type is determined by the resultType parameter. See Specifying result types for more information.
Use the type dropdown to the right of the Response header to view an example of each response type:


