curl --request POST \
  --url https://{instance}.omniapp.co/api/v1/documents/{documentId}/queries/{queryId}/run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filters": {
    "chargers.id": "CH-1042"
  }
}
'

[
  {
    "chargers.id": "CH-1042",
    "sessions.kwh": 42.5
  }
]

{
  "detail": "Filter on \"chargers.id\" was not applied: an empty array matches nothing; Filter on \"sessions.kwh\" was not applied: a filter object names exactly one filter type — one key, plus any modifiers",
  "status": 400
}

{
  "detail": "Unauthorized: Missing or invalid API key",
  "status": 401
}

{
  "detail": "<string>",
  "status": 403
}

{
  "detail": "<string>",
  "status": 404
}

{
  "detail": "Query timed out",
  "timed_out": true,
  "remaining_job_ids": [
    "<string>"
  ]
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

Management

Run a saved document query

Run one of a document’s saved queries and returns the results as JSON, CSV, or XLSX. Only adding and updating existing filters is supported. To modify more than a query’s filters before running it, see the Running document queries with APIs guide.

View access is required to run queries that are shown as tiles on a dashboard, or any saved query on a document with an app. All other saved queries require access to the document’s workbook.

This API is the only way to run a dashboard tile for a user with read-only access to a dashboard. To run a query definition you supply yourself, use the Run query API instead.

POST

documents

{documentId}

queries

{queryId}

run

curl --request POST \
  --url https://{instance}.omniapp.co/api/v1/documents/{documentId}/queries/{queryId}/run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filters": {
    "chargers.id": "CH-1042"
  }
}
'

[
  {
    "chargers.id": "CH-1042",
    "sessions.kwh": 42.5
  }
]

{
  "detail": "Filter on \"chargers.id\" was not applied: an empty array matches nothing; Filter on \"sessions.kwh\" was not applied: a filter object names exactly one filter type — one key, plus any modifiers",
  "status": 400
}

{
  "detail": "Unauthorized: Missing or invalid API key",
  "status": 401
}

{
  "detail": "<string>",
  "status": 403
}

{
  "detail": "<string>",
  "status": 404
}

{
  "detail": "Query timed out",
  "timed_out": true,
  "remaining_job_ids": [
    "<string>"
  ]
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

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

Path Parameters

documentId

string

required

Document identifier (either document ID or identifier slug)

queryId

string

required

The saved query to run: its queryIdentifierMapKey, or its query presentation id, from GET /v1/documents/{documentId}/queries.

Minimum string length: 1

Query Parameters

userId

string<uuid>

Organization API key required. The membership ID of the user to act as.

Body

application/json

filters

object

Filters to apply for this run, keyed by field name (e.g. orders.status). Each replaces the saved filter on the same field and the saved query is not modified. A filter that cannot be applied fails the request.

Show child attributes

Example:

{ "chargers.id": "CH-1042" }

formatResults

boolean

default:true

Whether to format result values (e.g., apply number formatting).

resultType

enum<string>

Format of the result document. For csv and xlsx results formats, the document's Download setting must be enabled.

Available options:

csv,

xlsx,

json

Example:

"json"

Response

The saved query ran; the body is its result document.

{key}

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 a saved document query

Authorizations

Path Parameters

Query Parameters

Body

Response