OMomniapp
Query

Execute a semantic query

Changed on

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

Request

  • Base URL
    https://omniapp.co (the document declares no server; this is the origin it was published from)
  • URL
    https://omniapp.co/api/v1/query/run
  • Auth
    HTTP bearer

Query parameters

userIdstring uuid

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

Cache policy for query execution. Must be one of: Standard (standard caching behavior; default), SkipRequery (uses cached results if available, but does not requery), SkipCache (bypasses the cache and always executes fresh queries), SkipCacheAndRebuildExtracts (bypasses the cache and rebuilds any extracts the query reads from).

completionOnlyboolean

If true, completed job lines omit result; read the data afterwards with GET /api/v1/query/results, which can page a large result by byte offset. Cannot be combined with resultType.

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.

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

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

timezonestring

IANA timezone identifier to override the user's configured timezone for this query. Only takes effect when the connection has user-specific timezones enabled.

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": "SkipCache",
  "environmentConnectionId": "550e8400-e29b-41d4-a716-446655440000",
  "query": {
    "fields": [
      "orders.total_amount",
      "orders.created_date"
    ],
    "limit": 1000,
    "modelId": "123e4567-e89b-12d3-a456-426614174000"
  },
  "timezone": "America/Los_Angeles",
  "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".

Changes

  • 12e9325d71cdRevision changes
    • breaking

      removed subschema #1 subschema #2 subschema #3 subschema #4 subschema #5 subschema #6 subschema #7 subschema #8 from the // request property oneOf list

    • info

      added subschema #1 subschema #2 subschema #3 subschema #4 subschema #5 subschema #6 subschema #7 subschema #8 to the // request property oneOf list

  • f9d898b7238cRevision changes
    • breaking

      added the new required request property /

    • breaking

      added the new required request property /

    • breaking

      the request property became required

    • breaking

      the request property type changed from no type to object

    • 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

      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

      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 /