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"
  }
}
'

import requests

url = "https://{instance}.omniapp.co/api/v1/query/run"

payload = { "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"
    } }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'
    }
  })
};

fetch('https://{instance}.omniapp.co/api/v1/query/run', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{instance}.omniapp.co/api/v1/query/run",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{instance}.omniapp.co/api/v1/query/run"

	payload := strings.NewReader("{\n  \"query\": {\n    \"modelId\": \"bcf0cffd-ec1b-44d5-945a-a261ebe407fc\",\n    \"table\": \"order_items\",\n    \"fields\": [\n      \"inventory_items.product_department\",\n      \"inventory_items.product_category\",\n      \"inventory_items.count\"\n    ],\n    \"limit\": 10,\n    \"sorts\": [\n      {\n        \"column_name\": \"inventory_items.product_department\",\n        \"sort_descending\": false\n      }\n    ],\n    \"join_paths_from_topic_name\": \"order_items\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{instance}.omniapp.co/api/v1/query/run")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"query\": {\n    \"modelId\": \"bcf0cffd-ec1b-44d5-945a-a261ebe407fc\",\n    \"table\": \"order_items\",\n    \"fields\": [\n      \"inventory_items.product_department\",\n      \"inventory_items.product_category\",\n      \"inventory_items.count\"\n    ],\n    \"limit\": 10,\n    \"sorts\": [\n      {\n        \"column_name\": \"inventory_items.product_department\",\n        \"sort_descending\": false\n      }\n    ],\n    \"join_paths_from_topic_name\": \"order_items\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{instance}.omniapp.co/api/v1/query/run")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"query\": {\n    \"modelId\": \"bcf0cffd-ec1b-44d5-945a-a261ebe407fc\",\n    \"table\": \"order_items\",\n    \"fields\": [\n      \"inventory_items.product_department\",\n      \"inventory_items.product_category\",\n      \"inventory_items.count\"\n    ],\n    \"limit\": 10,\n    \"sorts\": [\n      {\n        \"column_name\": \"inventory_items.product_department\",\n        \"sort_descending\": false\n      }\n    ],\n    \"join_paths_from_topic_name\": \"order_items\"\n  }\n}"

response = http.request(request)
puts response.read_body

[
  {
    "inventory_items.product_department": "Women",
    "inventory_items.product_category": "Jeans",
    "inventory_items.count": 42
  },
  {
    "inventory_items.product_department": "Men",
    "inventory_items.product_category": "Outerwear & Coats",
    "inventory_items.count": 17
  }
]

POST

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"
  }
}
'

import requests

url = "https://{instance}.omniapp.co/api/v1/query/run"

payload = { "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"
    } }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'
    }
  })
};

fetch('https://{instance}.omniapp.co/api/v1/query/run', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{instance}.omniapp.co/api/v1/query/run",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{instance}.omniapp.co/api/v1/query/run"

	payload := strings.NewReader("{\n  \"query\": {\n    \"modelId\": \"bcf0cffd-ec1b-44d5-945a-a261ebe407fc\",\n    \"table\": \"order_items\",\n    \"fields\": [\n      \"inventory_items.product_department\",\n      \"inventory_items.product_category\",\n      \"inventory_items.count\"\n    ],\n    \"limit\": 10,\n    \"sorts\": [\n      {\n        \"column_name\": \"inventory_items.product_department\",\n        \"sort_descending\": false\n      }\n    ],\n    \"join_paths_from_topic_name\": \"order_items\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{instance}.omniapp.co/api/v1/query/run")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"query\": {\n    \"modelId\": \"bcf0cffd-ec1b-44d5-945a-a261ebe407fc\",\n    \"table\": \"order_items\",\n    \"fields\": [\n      \"inventory_items.product_department\",\n      \"inventory_items.product_category\",\n      \"inventory_items.count\"\n    ],\n    \"limit\": 10,\n    \"sorts\": [\n      {\n        \"column_name\": \"inventory_items.product_department\",\n        \"sort_descending\": false\n      }\n    ],\n    \"join_paths_from_topic_name\": \"order_items\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{instance}.omniapp.co/api/v1/query/run")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"query\": {\n    \"modelId\": \"bcf0cffd-ec1b-44d5-945a-a261ebe407fc\",\n    \"table\": \"order_items\",\n    \"fields\": [\n      \"inventory_items.product_department\",\n      \"inventory_items.product_category\",\n      \"inventory_items.count\"\n    ],\n    \"limit\": 10,\n    \"sorts\": [\n      {\n        \"column_name\": \"inventory_items.product_department\",\n        \"sort_descending\": false\n      }\n    ],\n    \"join_paths_from_topic_name\": \"order_items\"\n  }\n}"

response = http.request(request)
puts response.read_body

[
  {
    "inventory_items.product_department": "Women",
    "inventory_items.product_category": "Jeans",
    "inventory_items.count": 42
  },
  {
    "inventory_items.product_department": "Men",
    "inventory_items.product_category": "Outerwear & Coats",
    "inventory_items.count": 17
  }
]

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.

Reading large results

A large result streamed inline can take minutes and is lost if the connection drops. To read it in chunks instead:

Call this endpoint (and, if needed, Wait for query results) with completionOnly: true so completed job lines omit result.
Once a job’s status is COMPLETE, call Read query results by offset with offset=0.
Call it again with offset set to the previous response’s stream_stats.next_offset, repeating until next_offset is null.
Each response’s result is base64 of one raw slice of the Arrow IPC stream — decode and append the slices in order, then parse the joined bytes. The results endpoint’s timeoutMs parameter stops a read early at a chunk boundary (at least one chunk is always returned), so a dropped connection can resume from the last next_offset you received. Results stay readable for about an hour after the job completes.

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:

Open a workbook in Omni.
Click the bug icon to toggle open the Inspector panel. For Mac use Option + 9; for Windows, use Alt + 9.
Locate the Query structure section.
Copy the query JSON.

branchId belongs at the top level of the request body, not inside query. A branchId or branch_id nested inside query is rejected.

Show child attributes

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

completionOnly

boolean

default:false

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

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:

{key}

any

Getting started

Who am I?

Administration APIs

AI APIs

App APIs

Branch APIs

Connection APIs

Content APIs

Dashboard APIs

Document APIs

Embed APIs

Folder APIs

Label APIs

Model APIs

Query APIs

Schedule APIs

Upload APIs

User APIs

User group APIs

Run query

Specifying result types

Timeouts

Reading large results

Authorizations

Query Parameters

Body

Response

​Specifying result types

​Timeouts

​Reading large results

Authorizations

Query Parameters

Body

Response

Specifying result types

Timeouts

Reading large results