Sign in

v1

latestOpenAPI 3.1.02026-07-2618690613.4 KB
Queries

Run query

Run the query specified in the request body. Successful requests will return the data as a base64 encoded Apache Arrow table, allowing you to extract query results from Omni and use them elsewhere. For example, piping data to Google Sheets or leveraging data in a Python notebook.

post/v1/query/run

Query parameters

userIdstring uuid

Requires an Organization API key. The ID of the user to run the query as.

Personal Access Tokens (PATs) cannot use this parameter to act on behalf of other users.

Request body

branchIdstring uuid

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.

connectionEnvironmentIdstring uuid

Optional connection environment ID to override the session-derived connection environment for this query run. The requesting user must have access to the specified environment.

When provided, the query runs against the specified connection environment instead of the user's session selection.

userIdstring uuid

Executes the query as the specified user.

Prefer passing userId as a query parameter instead of in the request body. Providing userId in both locations will return a 400 error.

If not provided in either location, the API uses the user associated with the API token. The userId must belong to a user in your organization.

cache'Standard' | 'SkipRequery' | 'SkipCache'

Optional cache policy to control how query caching behaves. Must be one of:

  • Standard - Uses standard caching behavior
  • SkipRequery - Uses cached results if available, but does not requery if not found (default)
  • SkipCache - Bypasses cache and always executes a fresh query
resultType'csv' | 'json' | 'xlsx'

Cannot be used with planOnly. Specifies the format of query results exported by the API.

If omitted, the API will return results in a base-64 encoded format.

planOnlyboolean

Cannot be used with resultType. If true, the API will return the query execution plan without running the query. The response will include the generated SQL and query metadata.

formatResultsboolean

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.

workbookUrlboolean

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

Successful responses will contain the following:

  • An object with a jobs_submitted property
  • An object containing details about the job, such as job_id, status, and the provided query. Note: If planOnly: true was included in the request body, the status will be PLANNED.
  • The job details object will also contain a result property, which contains the query results as a base64 encoded Apache Arrow table. You can use the Omni Python SDK to decode and validate the results.

If the request times out, the response will include remaining_job_ids. Poll the /api/v1/query/wait endpoint with these IDs until timed_out is false.

jobs_submittedobject

Map of job IDs to client result IDs

job_idstring uuid

The unique identifier for the query job

statusstring

Job status (e.g., COMPLETE, PLANNED)

client_result_idstring uuid

Client-side result identifier

summaryobject

Query execution summary including SQL, stats, and field metadata

cache_metadataobject

Cache information including TTL and data freshness

queryobject

The executed query details

resultstring

Base64 encoded Apache Arrow table containing query results

remaining_job_idsstring[]

IDs of the jobs still processing if the request timed out. Poll /api/v1/query/wait with these IDs.

timed_outstring

Indicates if the request timed out. If true, use remaining_job_ids to poll for results.