Skip to main content
POST
Run query

Specifying result types

The resultType 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_submitted header, then one line per job as it reaches a terminal state. A completed job contains the result set as base64-encoded Arrow IPC in result; use summary.fields to interpret the decoded columns. The response will also contain a footer. A footer with non-empty remaining_job_ids means 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 a 408 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

Authorization
string
header
required

Can be either an Organization API Key or Personal Access Token (PAT).

Include in the Authorization header as: Bearer YOUR_TOKEN

Query Parameters

userId
string<uuid>

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

application/json
query
object
required

A JSON object representing the query to be run.

To retrieve a query's JSON object from an Omni workbook:

  1. Open a workbook in Omni.
  2. Click the bug icon to toggle open the Inspector panel. For Mac use Option + 9; for Windows, use Alt + 9.
  3. Locate the Query structure section.
  4. Copy the query JSON.
branchId
string<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.

Takes precedence over the legacy ?branch_id= URL query parameter.

environmentConnectionId
string<uuid>

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.

userId
string<uuid>

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
enum<string>
default:SkipRequery

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 as SkipCache, and also rebuilds any extracts the query depends on.
Available options:
Standard,
SkipRequery,
SkipCache,
SkipCacheAndRebuildExtracts
resultType
enum<string>

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.

Available options:
csv,
json,
xlsx
planOnly
boolean

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.

formatResults
boolean
default:true

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.

timezone
string

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.

workbookUrl
boolean
default:false

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:

Response type dropdown menu

{key}
any