---
title: "Run a saved document query"
method: POST
path: "/api/v1/documents/{identifier}/queries/{queryId}/run"
tags: ["Documents"]
---

# Run a saved document query

`POST /api/v1/documents/{identifier}/queries/{queryId}/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/documents/{identifier}/queries/{queryId}/run`
- Auth: HTTP bearer

Runs one of the document's saved queries as it is saved and returns its results as a single JSON, CSV, or XLSX document. The query is read on the server: the caller can replace or add filters for the run, but cannot change anything else about what runs. A tile the document's dashboard shows, or any query of a document with an app, runs for anyone who can view the document, as on the dashboard or app itself; any other saved query, such as a hidden tile or a tab not on the dashboard, needs access to the workbook.

## Path parameters

- `identifier` 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 /api/v1/documents/{identifier}/queries.

## Query parameters

- `userId` string, uuid: Target user ID (for org-scoped API keys)

## Request body

- DocumentsRunQueryBody
  - `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 with 400 rather than running without it.
  - `formatResults` boolean: Whether to format result values (e.g., apply number formatting). Defaults to true.
  - `resultType` 'csv' | 'xlsx' | 'json': Format of the result document. Defaults to json.

## Response `200`

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

- object[]: Result rows keyed by field name. Returned when resultType is json (the default).

## Other responses

- `400`: Invalid body, a filter could not be applied, the saved query has no runnable definition, or it failed to run
- `401`: Authentication required
- `403`: Permission denied: no access to the document, or to the workbook for a query the dashboard doesn't show; the user can't run content queries on the query's model; or a CSV or XLSX result would be a download they aren't allowed
- `404`: Document not found or archived, the identifier names an unsaved analysis, or the document has no saved query with this queryId
- `408`: The query timed out. The body carries remaining_job_ids to poll with GET /api/v1/query/wait, which streams the results as that endpoint's NDJSON rather than in resultType.

## Changes

- **2026-10-16** `12e9325d71cd`: 1 breaking, 1 info
  - removed `subschema #6, subschema #7, subschema #8, subschema #9, subschema #10, subschema #11, subschema #12, subschema #13` from the `filters/additionalProperties/` request property `anyOf` list
  - added `subschema #6, subschema #7, subschema #8, subschema #9, subschema #10, subschema #11, subschema #12, subschema #13` to the `filters/additionalProperties/` request property `anyOf` list
- **2026-10-12** `c39971154a1d`: 1 info
  - added the new optional request property `filters`
- **2026-10-08** `bb4f102b5d25`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/omniapp/apis/omni-api/changes/api/v1/documents/:identifier/queries/:queryId/run/post.md)

---

[API](https://skmtc.dev/omniapp/apis/omni-api.md) - [All operations](https://skmtc.dev/omniapp/apis/omni-api/llms.txt) - [OpenAPI document](https://skmtc.dev/omniapp/apis/omni-api/revisions/76b40ebc2292?raw)