---
title: "Generate query from natural language"
method: POST
path: "/api/v1/ai/generate-query"
tags: ["AI"]
---

# Generate query from natural language

`POST /api/v1/ai/generate-query`

Generate an Omni semantic query from a natural language prompt. Optionally executes the generated query and returns results. The AI analyzes the prompt, selects appropriate fields and filters from the model, and constructs a query. Requires the querier role on the target model. The effective user's per-connector AI toggles (set in the chat + menu) govern which integration tools the agent may use.

## Request body

- AiGenerateQueryBody
  - `branchId` string, uuid — Optional branch ID for the model. Must be a branch of the shared model specified by modelId.
  - `currentTopicName` string — The name of the current topic to scope query generation. If not provided, AI will automatically select the best topic for your prompt.
  - `modelId` string, uuid, required — The UUID of the shared model to query against. Only shared models are supported.
  - `prompt` string, required — The natural language prompt describing the data you want to retrieve.
  - `queryAllViews` boolean — If true and the model has query_all_views_and_fields enabled, AI can query views not in any topic.
  - `runQuery` boolean — Whether to execute the generated query and return results. Defaults to true. Set to false to only generate the query definition without executing it.
  - `userId` string, uuid — User ID to execute the query as. Their permissions will be applied for row-level security. Only valid with organization-scoped API keys. Personal access tokens always act as the authenticated user.
  - `workbookUrl` boolean — If true, creates a new workbook with the generated query and returns its URL. Useful for sharing results or further exploration.

## Response `200`

Query generated successfully. If runQuery is true (default), includes execution results. Check the error field — a 200 response may still contain a partial error if the query was generated but execution failed. When the organization is over its AI downgrade threshold the response also carries `downgradedModelTier` naming the cheaper tier the query was generated with.

- AiGenerateQueryResponse
  - `baseView` string, nullable — The base view name used for query generation when queryAllViews surfaced a non-topic view. Mutually exclusive with `topic` — exactly one is non-null when a query was generated.
  - `downgradedModelTier` string — Present only when the organization is over its AI downgrade threshold, signaling the query was generated on a downgraded (cheaper) model tier (e.g. 'haiku') to conserve credits. Advisory and best-effort — the call still succeeds, and clients may surface that a downgraded model was used. Absent when no downgrade applied.
  - `error` object, nullable, required — Error details if query generation failed. Null on success.
    - `detail` string, required — Detailed error message explaining why query generation failed.
    - `message` string, required — Short error summary.
  - `query` AiSemanticQuery, nullable, required — The generated semantic query definition. Null if generation failed. This query can be passed directly to the POST /api/v1/query/run endpoint.
    - `fields` string[], required — Ordered list of fully qualified field names to include in the query (e.g., "view_name.field_name").
    - `filters` object — Filter conditions keyed by fully qualified field name. Filter values vary by field type.
    - `limit` integer — Maximum number of rows to return.
    - `sorts` AiQuerySort[] — Sort specifications applied to the query results.
      - `column_name` string, required — Fully qualified field name to sort by (e.g., "view_name.field_name").
      - `sort_descending` boolean, required — Whether to sort in descending order.
    - `table` string — The base topic or view name for the query.
  - `result` object — Query execution results as a JSON object. Only present when runQuery is true (the default) and the query executed successfully. The structure contains the query result data.
  - `topic` string, nullable — The topic name used for query generation. Mutually exclusive with `baseView` — exactly one is non-null when a query was generated.
  - `workbookUrl` string, uri — URL to view and edit the generated query in an Omni workbook. Only present when workbookUrl was set to true in the request.

## Other responses

- `400` — Invalid request. The prompt may be missing, the modelId may be invalid, or the AI was unable to generate a query for the given prompt.
- `401` — Missing or invalid API key.
- `402` — AI is unavailable because the organization is over its AI credit limit. The body carries the stable reason code `shutoff`.
- `403` — Insufficient permissions. Requires the querier role on the target model and AI query generation must be enabled for the organization.
- `404` — The specified model or topic was not found in the organization.
- `500` — AI service error.

---

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