Run document queries with the Query API

Run a saved query directly

Use the Run a saved document query API to run one of a document’s saved queries in a single call. The query is read from the document on the server, so you only need the document identifier and the query’s queryIdentifierMapKey or presentation ID.

Unlike the Run query API, this endpoint doesn’t require Restricted Querier permissions — it runs at the same access level the document itself grants the authenticating user.

POST /api/v1/documents/:documentId/queries/:queryId/run

curl -L -X POST 'https://<your-omni-org>.omniapp.co/api/v1/documents/12db1a0a/queries/1/run' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
  "resultType": "json"
}'

Modify a query before running it

If you need to change a saved query before running it, such as adding fields, filters, or sorts, retrieve the query’s definition and submit it to the Run query API. This path requires Restricted Querier permissions or higher, since it can run any query definition you send it.

Retrieve the document's queries

GET /api/v1/documents/:documentId/queries

curl -L'https://<your-omni-org>.omniapp.co/api/v1/documents/12db1a0a/queries' \
-H 'Authorization: Bearer <TOKEN>'

Extract a query object from the response

The query objects returned by the Document Queries API are already structured in the format required by the Query API, making it easy to run these queries programmatically without having to manually build the query structure.

const document = response.body;
const queryObject = document.queries[0].query;

Modify and run the query

Change the query object as needed, then use it with the Run query API to run it:

POST /api/v1/query/run

curl -L -X POST 'https://<your-omni-org>.omniapp.co/api/v1/query/run' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
  "query": {
    "limit": 1000,
    "sorts": [
      {
        "column_name": "order_items.created_at[month]",
        "sort_descending": false
      }
    ],
    "table": "order_items",
    "fields": [
      "order_items.created_at[month]",
      "order_items.sale_price_sum"
    ],
    "filters": {},
    "modelId": "7155f419-a071-405c-8426-b4b5d3939049"
  }
}'

Run document queries with the Query API

Requirements

Run a saved query directly

Modify a query before running it