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

# Run a saved document query

`POST /v1/documents/{documentId}/queries/{queryId}/run`

## Request

- Base URL: `https://blobsrus.omniapp.co/api`
- URL: `https://blobsrus.omniapp.co/api/v1/documents/{documentId}/queries/{queryId}/run`
- Auth: HTTP bearer

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](/guides/api/run-document-queries).

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](/api/queries) instead.

## Path parameters

- `documentId` string, required
- `queryId` string, required

## Query parameters

- `userId` string, uuid

## Request body

- object
  - `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.
  - `formatResults` boolean: Whether to format result values (e.g., apply number formatting).
  - `resultType` 'csv' | 'xlsx' | 'json': Format of the result document. For `csv` and `xlsx` results formats, the document's **Download** setting must be enabled.

## Response `200`

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

- object[]: Result rows keyed by field name. Returned when `resultType` is `json`.

## Other responses

- `400`: Invalid request. Common causes: - An unknown key in the request body - The saved query has no runnable definition - A filter could not be applied - The query failed to run
- `401`: Authentication required
- `403`: Forbidden. Common causes: - No view access to the document - No access to the workbook, for a saved query the dashboard doesn't show - No permission to query the saved query's model - The result would be a download (`csv` or `xlsx`), and downloads aren't permitted (Enable the document's **Download** setting)
- `404`: Not Found. Common causes: - The document doesn't exist, or has been archived - The identifier names an unsaved analysis or a draft, which have no saved queries to run - The document has no saved query with this `queryId`
- `408`: The query timed out. Poll the [Wait for query results endpoint](/api/queries/wait-for-query-results) with the `remaining_job_ids` from the response body.
- `429`: Too Many Requests - Rate limit exceeded (60 requests/minute)

## Changes

- **2026-11-03** `43290040f88f`: 1 info
  - endpoint added

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

---

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