---
title: "Execute a semantic query"
method: POST
path: "/api/v1/query/run"
tags: ["Query"]
---

# Execute a semantic query

`POST /api/v1/query/run`

## Query parameters

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

## Request body

- QueryRunBody
  - `branchId` string, uuid — Optional model branch to run the query against. Must belong to the same shared model as the query. When omitted, the query runs against the shared model. Takes precedence over the legacy `?branch_id=` URL query parameter.
  - `cache` 'disabled' | 'normal' | 'refresh' | 'refresh_all' — Cache policy for query execution. Controls whether to use cached results.
  - `environmentConnectionId` string, uuid — Connection ID of the environment to run the query against, overriding the connection environment inherited from the (target) user's session or default. Must be a configured environment of the query model's connection that the user can access.
  - `formatResults` boolean — Whether to format result values (e.g., apply number formatting). Only valid when resultType is specified.
  - `planOnly` boolean — If true, returns only the query execution plan without running the query.
  - `query` unknown
  - `resultType` 'csv' | 'json' | 'xlsx' — Output format for the results. If not specified, returns base64-encoded Arrow format.
  - `userId` string, uuid — Alternate location for the `?userId=` query parameter. Prefer the query parameter — this body field exists for backwards compatibility. Supplying both forms results in a 400. Only valid for org-scoped API keys; when set, the user's attributes are applied for row-level security and connection-environment switching.

## Response `200`

Query executed or started successfully

- QueryRunResponse
  - `completedQueries` unknown[] — Queries that completed synchronously with their results.
    - unknown
  - `jobIds` string[] — Job IDs for queries running asynchronously. Use /api/v1/query/wait to poll for results.
  - `plan` unknown

## Other responses

- `400` — Invalid query definition or conflicting parameters
- `401` — Authentication required
- `403` — Permission denied - querier role required on the model
- `404` — Model, topic, view, or branch not found
- `408` — Query timed out. The response includes remaining_job_ids that can be polled via the query/wait endpoint.
- `500` — Query execution error

---

[API](https://skmtc.dev/omniapp/apis/omni-api.md) · [All operations](https://skmtc.dev/omniapp/apis/omni-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/omniapp/omni-api/revisions/c5d16d10108e/schema)