Skip to main content
POST
Generate a query

Authorizations

Authorization
string
header
required

Can be either an Organization API Key or Personal Access Token (PAT).

Include in the Authorization header as: Bearer YOUR_TOKEN

Body

application/json
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
default:""

Natural language instruction describing the desired query output. If omitted, an empty prompt is sent.

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 endpoint with modelKind=BRANCH.

runQuery
boolean
default:true

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

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.

documentQueries
object[]

Optional list of the queries on the document the prompt is about. Each query's topicName scopes topic selection.

queryAllViews
boolean
default:false

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.

requestedLlm
object

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.

Example:

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.

topic
string

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.

Example:

"order_items"

baseView
string

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.

Example:

"users"

downgradedLlm
string

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.

Example:

"claude-haiku-5-5"

downgradedModelTier
string
deprecated

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.

Example:

"haiku"

query
object