Generate a query
Generate a structured Omni query from natural language using AI.
For exploratory or cross-topic questions, use Create AI job instead.
Authorizations
Can be either an Organization API Key or Personal Access Token (PAT).
Include in the Authorization header as: Bearer YOUR_TOKEN
Body
The ID of the model to run the query against
Name of the base topic/table. If left empty, AI will automatically choose a topic based on the question.
Natural language instruction describing the desired query output. If omitted, an empty prompt is sent.
When true, returns an Omni workbook URL that opens and runs the generated query
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 endpoint with modelKind=BRANCH.
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.
An optional query for the AI to start from, such as the base query for a follow-up prompt. Use this to reference previous queries or provide additional context for the generation.
Optional list of the queries on the document the prompt is about. Each query's topicName scopes topic selection.
When true and the model's 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.
Optional LLM to generate the query with. The user running the query must have access to the LLM or the API returns an error. Use the List available LLMs endpoint to retrieve a list of available LLMs.
Omit to use the organization's default LLM.
Response
Successfully generated query.
When your organization is over its AI credit threshold, the response also includes downgradedLlm, naming the LLM the query was generated on, and the deprecated downgradedModelTier, always haiku.
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.
"order_items"
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.
"users"
The LLM the query was generated on, present only when your organization is over its AI credit threshold. This is the LLM Omni runs simple tasks on within your organization's LLM family.
Absent when no downgrade occurred.
"claude-haiku-5-5"
Deprecated. Use downgradedLlm instead, which names the specific LLM.
Present only when your organization is over its AI credit threshold. Always the literal haiku.
Absent when no downgrade occurred.
"haiku"

