Skip to main content
POST
/
v1
/
ai
/
generate-query
Generate a query
curl --request POST \
  --url https://{instance}.omniapp.co/api/v1/ai/generate-query \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "modelId": "123e4567-e89b-12d3-a456-426614174000",
  "currentTopicName": "orders",
  "prompt": "Show me total revenue by product category for the last quarter"
}
'
{
  "query": {
    "model_job": {
      "model_id": "bcf0cffd-ec1b-44d5-945a-a261ebe407fc",
      "table": "order_items",
      "fields": [
        "products.item_name",
        "order_items.total_sale_price"
      ],
      "calculations": [],
      "filters": {},
      "sorts": [
        {
          "column_name": "order_items.total_sale_price",
          "sort_descending": true,
          "is_column_sort": false,
          "null_sort": "OMNI_DEFAULT"
        }
      ],
      "limit": 10,
      "pivots": [],
      "fill_fields": [],
      "column_totals": {},
      "row_totals": {},
      "column_limit": 50,
      "default_group_by": true,
      "join_via_map": {},
      "join_paths_from_topic_name": "order_items",
      "version": 5,
      "period_over_period_computations": [],
      "query_references": {},
      "metadata": {},
      "custom_summary_types": {}
    }
  }
}

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

​
prompt
string
required

Natural language instruction describing the desired query output

​
currentTopicName
string

Name of the base topic/table. If left empty, AI will automatically choose a topic based on the question.

​
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

A query object to provide as context. Use this to reference previous queries or provide additional context for the generation.

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

Response

Successfully generated query

​
topic
string | null

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 | null

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"

​
query
object