OMomni
Queries

Run query

Changed on

Run the semantic query specified in the request body. Successful requests will return the results according to the specified resultType.

post/v1/query/run

Request

  • Base URL
    https://blobsrus.omniapp.co/api
  • URL
    https://blobsrus.omniapp.co/api/v1/query/run
  • Auth
    HTTP bearer

Query parameters

userIdstring 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.

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.

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

environmentConnectionIdstring 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.

userIdstring 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'Standard' | 'SkipRequery' | 'SkipCache' | 'SkipCacheAndRebuildExtracts'

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.
completionOnlyboolean

Cannot be used with resultType. If true, completed job lines omit result; read the data afterward with the Read query results by offset endpoint, which can page a large result by byte offset. See Reading large results for more information.

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

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.

planOnlyboolean

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.

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.

timezonestring

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.

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

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

object[] required

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

Changes

  • 43290040f88fRevision changes
    • breaking

      the response's body type changed from object to array for status

    • warning

      removed the request property

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property /

    • info

      added the new optional request property /

    • info

      added the new optional request property /

    • info

      added the new optional request property /

    • info

      added the new optional request property

    • info

      the request property / became optional

    • info

      added the new SkipCacheAndRebuildExtracts enum value to the request property

    • info

      added the media type application/vnd.ms-excel for the response with the status

    • info

      added the media type text/csv for the response with the status

    • info

      added the media type text/ndjson for the response with the status

    • info

      added the non-success response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status