> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Run a saved document query

> Run one of a document's saved queries and returns the results as JSON, CSV, or XLSX. The query is run as-is; only the result format is modifiable.

A tile the document's dashboard shows, or any saved query on a document with an app, runs for anyone who can view the document — the same access check used for the dashboard's own tiles. Any other saved query, such as a hidden tile or a tab that isn't on the dashboard, requires access to the workbook itself.


<Tip>
  This endpoint runs the saved query directly, without a separate lookup step. To modify a query before running it, see the [Running document queries with APIs guide](/guides/api/run-document-queries).
</Tip>


## OpenAPI

````yaml /api/openapi.yaml post /v1/documents/{documentId}/queries/{queryId}/run
openapi: 3.1.0
info:
  title: Omni API
  description: >
    The Omni REST API provides programmatic access to your Omni instance for
    managing users, documents, queries, schedules, and more.  
  version: 1.0.0
  contact:
    name: Omni Support
    url: https://docs.omni.co
servers:
  - url: https://{instance}.omniapp.co/api
    description: Production
    variables:
      instance:
        default: blobsrus
        description: Your production Omni instance subdomain
  - url: https://{instance}.playground.exploreomni.dev/api
    description: Playground
    variables:
      instance:
        default: blobsrus
        description: Your playground Omni instance subdomain
security:
  - bearerAuth: []
  - orgApiKey: []
tags:
  - name: Who Am I
    description: Inspect your own user permissions
  - name: AI
    description: AI-powered query generation
  - name: AI Credit Controls
    description: Manage organization-level AI credit usage
  - name: AI Credit Usage
    description: Monitor AI credit usage
  - name: AI Evals
    description: >-
      Manage prompt sets and runs used to score AI quality against curated
      prompt suites.
  - name: AI Model Suggestions
    description: Manage AI-generated suggestions for shared models
  - name: AI Routines
    description: >-
      Manage Routines, which are scheduled, recurring AI-powered tasks that run
      automatically on your data
  - name: Apps
    description: Draft and publish app documents.
  - name: Documents v2
    description: >
      A draft-based workflow for creating and editing documents: create a
      document, patch a draft, then publish.
  - name: Documents
    description: Create, retrieve, and manage documents
  - name: API Tokens
    description: >-
      Manage API tokens (Organization keys, Personal Access Tokens, MCP OAuth
      grants)
  - name: IP Allowlist
    description: Manage the organization's IP allowlist
  - name: Connections
    description: Manage database connections
  - name: Connection environments
    description: Manage connection environments database connections
  - name: Color Palettes
    description: Manage custom chart color palettes
  - name: Content
    description: Unified content retrieval (documents and folders)
  - name: Content migration
    description: Export and import dashboards
  - name: Content validator
    description: Validate content against models and perform find/replace operations
  - name: Dashboard downloads
    description: Download dashboards and tiles as PDF, PNG, XLSX, CSV, or JSON files
  - name: Dashboard filters and controls
    description: Read and update dashboard filter and control default values
  - name: dbt
    description: Manage dbt configuration for connections
  - name: Document favorites
    description: Favorite and unfavorite documents
  - name: Document labels
    description: Apply and manage labels on documents
  - name: Document permissions
    description: Manage document-level access
  - name: Embed
    description: Manage embed sessions
  - name: Labels
    description: |
      Manage labels in the organization
  - name: Folders
    description: Create and organize content folders
  - name: Folder labels
    description: Apply and manage labels on folders
  - name: Folder permissions
    description: Manage folder-level access
  - name: Jobs
    description: Check status of asynchronous jobs
  - name: Models
    description: Create and manage data models
  - name: Model branches
    description: Manage model branches and merge changes
  - name: Model git configuration
    description: Manage git configuration for shared models
  - name: Queries
    description: Execute workbook queries
  - name: Schedules
    description: Create and manage scheduled tasks
  - name: Schedule recipients
    description: Manage schedule recipients
  - name: Schema refresh schedules
    description: Manage automated schema refresh schedules for connections
  - name: Skills
    description: >-
      Manage skills, the saved slash-command instructions the Omni AI assistant
      runs
  - name: Topics
    description: Retrieve topic information from models
  - name: Uploads
    description: Manage file uploads
  - name: Users
    description: Manage users
  - name: User attributes
    description: Manage user attribute definitions
  - name: User groups
    description: Manage user groups
  - name: User model roles
    description: Manage model and connection role assignments for users
  - name: User group model roles
    description: Manage model and connection role assignments for user groups
  - name: Uploads
    description: Manage CSV and spreadsheet uploads
paths:
  /v1/documents/{documentId}/queries/{queryId}/run:
    post:
      tags:
        - Documents
      summary: Run a saved document query
      description: >
        Run one of a document's saved queries and returns the results as JSON,
        CSV, or XLSX. The query is run as-is; only the result format is
        modifiable.


        A tile the document's dashboard shows, or any saved query on a document
        with an app, runs for anyone who can view the document — the same access
        check used for the dashboard's own tiles. Any other saved query, such as
        a hidden tile or a tab that isn't on the dashboard, requires access to
        the workbook itself.
      operationId: documentsRunQuery
      parameters:
        - name: documentId
          in: path
          required: true
          schema:
            type: string
            description: Document identifier (either document ID or identifier slug)
            example: abc123
          description: Document identifier (either document ID or identifier slug)
        - name: queryId
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            description: >-
              The saved query to run: its queryIdentifierMapKey, or its query
              presentation id, from GET /api/v1/documents/{identifier}/queries.
            example: '1'
          description: >-
            The saved query to run: its queryIdentifierMapKey, or its query
            presentation id, from GET /api/v1/documents/{identifier}/queries.
        - $ref: '#/components/parameters/userId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                formatResults:
                  type: boolean
                  default: true
                  description: >
                    Whether to format result values (e.g., apply number
                    formatting). Defaults to `true`.
                resultType:
                  type: string
                  default: json
                  enum:
                    - csv
                    - xlsx
                    - json
                  description: >
                    Format of the result document. For `csv` and `xlsx` results
                    formats, the document's **Download** setting must be
                    enabled.
                  example: json
              additionalProperties: false
      responses:
        '200':
          description: The saved query ran; the body is its result document.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties:
                    anyOf:
                      - type: string
                      - type: number
                      - type: boolean
                      - type: 'null'
                description: >-
                  Result rows keyed by field name. Returned when resultType is
                  json (the default).
              example:
                - Count: 42
                - Count: 7
            application/vnd.ms-excel:
              schema:
                description: XLSX document. Returned only when resultType is "xlsx".
                format: binary
                type: string
            text/csv:
              schema:
                description: CSV document. Returned only when resultType is "csv".
                type: string
        '400':
          description: |
            Invalid request. Common causes:

            - An unknown key in the request body
            - The saved query has no runnable definition
            - The query failed to run
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError400'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError401'
        '403':
          description: >
            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)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError403'
        '404':
          description: >
            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`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError404'
        '408':
          description: >
            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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryTimeoutResponse'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
        - bearerAuth: []
components:
  parameters:
    userId:
      name: userId
      schema:
        type: string
        format: uuid
      required: false
      description: >
        **Organization API key required.** The membership ID of the user to act
        as.
      in: query
  schemas:
    ApiError400:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable error message describing what went wrong.
        status:
          type: integer
          description: HTTP status code of the error.
          example: 400
      required:
        - detail
        - status
    ApiError401:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable error message describing what went wrong.
          example: 'Unauthorized: Missing or invalid API key'
        status:
          type: integer
          description: HTTP status code of the error.
          example: 401
      required:
        - detail
        - status
    ApiError403:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable error message describing what went wrong.
        status:
          type: integer
          description: HTTP status code of the error.
          example: 403
      required:
        - detail
        - status
    ApiError404:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable error message describing what went wrong.
        status:
          type: integer
          description: HTTP status code of the error.
          example: 404
      required:
        - detail
        - status
    QueryTimeoutResponse:
      type: object
      properties:
        detail:
          type: string
          description: Error message indicating the query timed out.
          example: Query timed out
        remaining_job_ids:
          type: array
          items:
            type: string
          description: >-
            Job IDs for queries that have not yet completed. Use
            /api/v1/query/wait to poll for results.
        timed_out:
          type: boolean
          enum:
            - true
          description: Always true for timeout responses.
          example: true
      required:
        - detail
        - timed_out
    Error:
      type: object
      properties:
        error:
          type: string
          description: HTTP response code for the error
          example: <response_code>
        message:
          type: string
          description: Detailed error description
          example: <error_reason>
  responses:
    TooManyRequests:
      description: Too Many Requests - Rate limit exceeded (60 requests/minute)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        Can be either an [Organization API
        Key](/api/authentication#organization-api-keys) or [Personal Access
        Token (PAT)](/api/authentication#token-types).


        Include in the `Authorization` header as: `Bearer YOUR_TOKEN`
    orgApiKey:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        Requires an [Organization API
        Key](/api/authentication#organization-api-keys). Personal Access Tokens
        (PATs) are not supported for this endpoint.


        Include in the `Authorization` header as: `Bearer ORGANIZATION_API_KEY`

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.