Sign in
Query

Execute a semantic query

post/api/v1/query/run

Query parameters

userIdstring uuid

Target user membership ID (for org-scoped API keys)

Target user membership ID (for org-scoped API keys)

Request body

branchIdstring 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.

environmentConnectionIdstring 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.

formatResultsboolean

Whether to format result values (e.g., apply number formatting). Only valid when resultType is specified.

planOnlyboolean

If true, returns only the query execution plan without running the query.

{"stackTrail":"components:schemas:QueryRunBody:properties:query","oasType":"schema","type":"unknown","description":"The semantic query definition including fields, filters, sorts, and other query parameters."}
resultType'csv' | 'json' | 'xlsx'

Output format for the results. If not specified, returns base64-encoded Arrow format.

userIdstring 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.

Example request

{
  "branchId": "550e8400-e29b-41d4-a716-446655440000",
  "cache": "normal",
  "environmentConnectionId": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "550e8400-e29b-41d4-a716-446655440000"
}

Response

Query executed or started successfully

jobIdsstring[]

Job IDs for queries running asynchronously. Use /api/v1/query/wait to poll for results.

{"stackTrail":"components:schemas:QueryRunResponse:properties:plan","oasType":"schema","type":"unknown","description":"Query execution plan (only present if planOnly is true)."}

Example response

{
  "jobIds": [
    "job_abc123",
    "job_def456"
  ]
}

Changes