Skip to main content
POST
/
v1
/
query
/
run
Run query
curl --request POST \
  --url https://{instance}.omniapp.co/api/v1/query/run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": {
    "modelId": "bcf0cffd-ec1b-44d5-945a-a261ebe407fc",
    "table": "order_items",
    "fields": [
      "inventory_items.product_department",
      "inventory_items.product_category",
      "inventory_items.count"
    ],
    "limit": 10,
    "sorts": [
      {
        "column_name": "inventory_items.product_department",
        "sort_descending": false
      }
    ],
    "join_paths_from_topic_name": "order_items"
  }
}
'
{
  "jobs_submitted": {},
  "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "<string>",
  "client_result_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "summary": {},
  "cache_metadata": {},
  "query": {},
  "result": "<string>",
  "stream_stats": {
    "server_stream": 123
  },
  "remaining_job_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "timed_out": "<string>"
}
Encountering timeouts? If a request takes too long, the API will return a 408 timeout error with a body that includes 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

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.

​
userId
string<uuid>

Executes the query as the specified user. If not provided, the API uses the user associated with the API token. The userId must belong to a user in your organization.

​
cache
enum<string>
default:SkipRequery

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
Available options:
Standard,
SkipRequery,
SkipCache
​
resultType
enum<string>

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.

Available options:
csv,
json,
xlsx
​
planOnly
boolean

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.

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

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_submitted
object

Map of job IDs to client result IDs

​
job_id
string<uuid>

The unique identifier for the query job

​
status
string

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

​
client_result_id
string<uuid>

Client-side result identifier

​
summary
object

Query execution summary including SQL, stats, and field metadata

​
cache_metadata
object

Cache information including TTL and data freshness

​
query
object

The executed query details

​
result
string

Base64 encoded Apache Arrow table containing query results

​
stream_stats
object

Server-side streaming metrics

​
remaining_job_ids
string<uuid>[]

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

​
timed_out
string

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