---
title: "Generate a query"
method: POST
path: "/v1/ai/generate-query"
tags: ["AI"]
---

# Generate a query

`POST /v1/ai/generate-query`

Generate a structured Omni query from natural language using AI

## Request body

- object
  - `modelId` string, uuid, required — The ID of the model to run the query against
  - `currentTopicName` string — Name of the base topic/table. If left empty, AI will automatically choose a topic based on the question.
  - `prompt` string, required — Natural language instruction describing the desired query output
  - `workbookUrl` boolean — When `true`, returns an Omni workbook URL that opens and runs the generated query
  - `branchId` string — The ID of the model branch to use to generate the query. If not provided, the `main` branch will be used. To retrieve branch IDs, use the [List models](/api/models/list-models) endpoint with `modelKind=BRANCH`.
  - `runQuery` boolean — When `true` (default), the generated query is executed against the database and results are included in the response. When `false`, only the generated query object is returned without executing it. Set to `false` to preview what query would be generated without incurring a database query.
  - `contextQuery` object — A query object to provide as context. Use this to reference previous queries or provide additional context for the generation.
  - `queryAllViews` boolean — When `true` and the model's [`query_all_views_and_fields`](/modeling/models/parameters/ai-settings/query-all-views-and-fields) setting is enabled, allows the AI to query views that are not included in topics. If the setting is disabled, this parameter has no effect. When both the API parameter and model setting are enabled: - The AI can select from any view in the model, including views not in topics - The AI will prefer topic-organized views unless the question clearly targets a standalone view **Note:** Users with topic-locked permissions cannot use this parameter, even if the model setting is enabled.

## Response `200`

Successfully generated query

- object
  - `topic` string, nullable — The name of the topic used for query generation. This will be populated if the AI used a topic and null if the query was generated using a base view.
  - `baseView` string, nullable — The name of the base view used for query generation. This will be populated if the AI used a view outside of a topic and null if the query was generated using a topic.
  - `query` object
    - `model_job` object — A structured Omni query object that can be used with the [Query run API](/api/queries/run-query)
      - `model_id` string, uuid — Model identifier
      - `table` string — Base table/topic name
      - `fields` string[] — Array of field names to include in query
      - `calculations` object[] — Custom calculations
      - `filters` object — Filter conditions
      - `sorts` object[] — Sort specifications
        - `column_name` string
        - `sort_descending` boolean
        - `is_column_sort` boolean
        - `null_sort` string
      - `limit` integer, nullable — Result row limit
      - `pivots` object[] — Pivot configurations
      - `fill_fields` string[] — Fields to fill
      - `column_totals` object — Column totals configuration
      - `row_totals` object — Row totals configuration
      - `column_limit` integer — Column limit for pivots
      - `default_group_by` boolean — Enable default grouping
      - `join_via_map` object — Join configuration map
      - `join_paths_from_topic_name` string — Topic name for join paths
      - `version` integer — Query version
      - `period_over_period_computations` object[] — Period over period calculations
      - `query_references` object — Query references
      - `metadata` object — Query metadata
      - `custom_summary_types` object — Custom summary type definitions

## Other responses

- `400` — Bad Request Possible error messages: - `Invalid method` - `Invalid JSON`
- `403` — Forbidden Possible error messages: - `Feature not enabled`
- `429` — Too Many Requests - Rate limit exceeded (60 requests/minute)
- `500` — Internal Server Error

---

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