v4

latestOpenAPI 3.1.02026-08-01207318738.7 KB

Generate query from natural language

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.

post/api/v1/ai/generate-query

Request body

branchIdstring uuid

Optional branch ID for the model. Must be a branch of the shared model specified by modelId.

currentTopicNamestring

The name of the current topic to scope query generation. If not provided, AI will automatically select the best topic for your prompt.

modelIdstring uuid required

The UUID of the shared model to query against. Only shared models are supported.

promptstring required

The natural language prompt describing the data you want to retrieve.

queryAllViewsboolean

If true and the model has query_all_views_and_fields enabled, AI can query views not in any topic.

runQueryboolean

Whether to execute the generated query and return results. Defaults to true. Set to false to only generate the query definition without executing it.

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

workbookUrlboolean

If true, creates a new workbook with the generated query and returns its URL. Useful for sharing results or further exploration.

Example request

{
  "branchId": "550e8400-e29b-41d4-a716-446655440000",
  "currentTopicName": "order_items",
  "modelId": "770e8400-e29b-41d4-a716-446655440002",
  "prompt": "Show me total revenue by month for the last year",
  "runQuery": true,
  "userId": "990e8400-e29b-41d4-a716-446655440004"
}

Response

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.

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

downgradedModelTierstring

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.

resultobject

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.

topicstring nullable

The topic name used for query generation. Mutually exclusive with baseView — exactly one is non-null when a query was generated.

workbookUrlstring uri

URL to view and edit the generated query in an Omni workbook. Only present when workbookUrl was set to true in the request.

Example response

{
  "downgradedModelTier": "haiku",
  "error": {
    "detail": "The AI was unable to generate a query for this prompt. Try rephrasing your question to be more specific about the data you want to retrieve.",
    "message": "No query generated"
  },
  "query": {
    "fields": [
      "products.name",
      "order_items.total_revenue"
    ],
    "limit": 500,
    "sorts": [
      {
        "column_name": "order_items.total_revenue",
        "sort_descending": true
      }
    ],
    "table": "order_items"
  },
  "topic": "order_items",
  "workbookUrl": "https://myorg.omni.co/w/abc123/1"
}

All 207 operations