Query & Answering

Project availability: ✅ Classic projects • ✅ Agentic projects

Wren AI exposes core APIs for answering user questions — including generating SQL from questions, executing queries, explaining results, and producing natural language summaries.

Everything in this section is text-to-SQL: you ask, Wren writes the SQL, runs it, and summarizes the result. It comes in two shapes, and picking between them is the first decision you make here:

Adhoc mode (/v2/stream/ask) — each question stands on its own. One question in, one complete answer out.
Interactive mode (/v2/stream/interactive_ask) — a chat-style conversation, where the AI may greet, explain, recommend follow-ups, and render charts inline.

Both work against classic and agentic projects alike.

🤖
Looking for agentic mode?
These endpoints do not run the agent. If you want a Wren agent that plans, runs multi-step analyses, produces artifacts, uses skills and memory, and can ask you clarifying questions mid-turn, that is a different endpoint — see Agentic mode.
Note that agentic mode requires an agentic project, whereas the endpoints below work with both project types.

Endpoints Overview

POST /v1/ask: Ask a question and get a direct answer from the AI.
POST /v2/generate_sql: Convert a natural language question into a SQL query.
POST /v2/run_sql: Execute SQL and return structured results.
POST /v2/generate_summary: Generate a natural language summary from a SQL query result.
GET /v2/stream_explanation: Stream natural language explanations for non-SQL questions.
POST /v2/stream/ask: Ask a question and stream SQL generation, execution, and answer events over Server-Sent Events (SSE).
POST /v2/stream/ask/respond: Answer a pending clarification question from a stream/ask request.
POST /v2/stream/interactive_ask: Create or continue an interactive conversation streamed over SSE.
POST /v2/stream/interactive_ask/respond: Answer a pending clarification question from a stream/interactive_ask conversation.
POST /v2/stream/generate_sql: Stream the SQL generation process with real-time state updates.

Use these endpoints to build interactive and intelligent data experiences.

When to Use Which API

Wren AI's Query & Answering APIs are modular. Depending on what you're building, you can send a single all-in-one request, hold a multi-turn conversation, or chain the individual building blocks together for step-by-step control. Pick the group that matches your use case.

🔹 Ask one question, get one answer

Best when each question stands on its own — the AI generates SQL, runs it, and summarizes the result:

Scenario	Use This
I want a single, complete answer in one JSON response (no streaming)	/v1/ask
I want that same end-to-end answer streamed with reasoning and progress updates (adhoc mode)	/v2/stream/ask

/v1/ask lives in the Legacy section and is the only synchronous all-in-one ask (there is no /v2/ask). It's fine for quick, non-streaming calls, but new integrations that want progress updates or mid-stream clarification should prefer /v2/stream/ask.

🔹 Hold a multi-turn conversation (interactive mode)

Best for chat-style, exploratory experiences where the AI does more than run one query — it can greet, explain, recommend follow-up questions, and draw charts:

Scenario	Use This
I'm building a chatbot or data-exploration UI where the AI may answer with SQL, explanations, insights, or ECharts charts rendered inline, with follow-ups kept in a thread	/v2/stream/interactive_ask

/v2/stream/ask vs /v2/stream/interactive_ask. Use /v2/stream/ask (adhoc mode) when every turn is a focused text-to-SQL question — SQL is generated, executed, and summarized, and charts are produced separately with /v2/generate_chart. Use /v2/stream/interactive_ask (interactive mode) for an open-ended conversation where the AI decides how to respond, including ECharts charts rendered inline.

🔹 Build your own workflow (modular building blocks)

Use these when you want control over each step, so you can review, log, or branch between stages:

Step	API
Convert a question to SQL	/v2/generate_sql (or stream it with /v2/stream/generate_sql)
Execute the SQL	/v2/run_sql
Summarize a SQL result	/v2/generate_summary
Explain a question that can't be answered with SQL	/v2/stream_explanation

🔹 Answer a clarification checkpoint

Both streaming asks can pause mid-stream and emit a pendingQuestion frame. You answer it with a short side-channel call — not a new stream — and the original SSE stream resumes where it paused. Call these only in response to a pendingQuestion, never on their own:

While streaming…	Answer the clarification with
/v2/stream/ask	/v2/stream/ask/respond
/v2/stream/interactive_ask	/v2/stream/interactive_ask/respond

💡 Common Combinations

You can mix and match these endpoints based on your product needs.

/v2/generate_sql → /v2/run_sql → /v2/generate_summary

For building BI tools or workflows where SQL needs review, logging, or step-by-step handling.
/v2/generate_sql → /v2/stream_explanation

When /v2/generate_sql returns a NON_SQL_QUERY error, pass its explanationQueryId to /v2/stream_explanation to stream a friendly explanation instead of a SQL answer.
/v1/ask

Best for quick answers with minimal effort when you don't need streaming.
/v2/stream/ask

Best for frontend apps that want to display real-time progress, similar to ChatGPT-style interactions.
/v2/stream/interactive_ask

Best for conversational, agentic experiences with inline charts, insights, and multi-turn context.

User Guide Controls

Not every question a user types is about the data. "Do I need to know SQL?", "How do I get started?" — when Wren classifies a question as product help, it answers from a built-in user guide describing Wren itself (which the first answer below calls by its internal name, Gen BI). If you have embedded Wren in your own product, that is usually the wrong answer: your users have never heard of Wren.

Two per-request fields change it, on /v1/ask, /v1/stream/ask, /v1/stream/interactive_ask, /v2/generate_sql, /v2/stream/generate_sql, /v2/stream/ask and /v2/stream/interactive_ask:

Field	Type	Default	Effect
`allowUserGuide`	`boolean`	`true`	`false` removes product help from classification entirely.
`userGuidePrompt`	`string`	—	Replaces the built-in guide, in both classification and the answer. Ignored when `allowUserGuide` is `false`.

Both default to today's behavior — omit them and the request is unchanged. Both are per-request: neither is remembered across a thread, so re-send them on every turn.

The same question, three ways

The examples below use POST /v1/ask, which returns the whole answer as one JSON body. Their usage object is abridged to the two fields that matter here; the real one also carries model names and token counts. The other six endpoints take the same two fields and behave the same way, but return their own shapes — streamed frames, or a NON_SQL_QUERY error you follow up with /v2/stream_explanation. Each endpoint's reference page shows its own worked example.

1. Omit both fields — answered from the built-in Wren guide:

{
  "projectId": 1,
  "question": "How do I get started?"
}

{
  "id": "28d2be86-afab-47bc-83e0-36cc26d62f59",
  "invalidSessionProperties": [],
  "type": "NON_SQL_QUERY",
  "explanation": "To get started with Gen BI, follow these steps:\\n\\n1. **Ask Natural-Language Queries:** Begin by typing your questions or commands in natural language. You don't need any technical skills to interact with the system.\\n\\n2. **Explore Data Automatically:** Gen BI will automatically profile and explore your data to provide relevant insights.\\n\\n3. **Use Smart Corrections:** If you make any input errors or use ambiguous terms, Gen BI will smartly correct them to understand your intent better.\\n\\n4. **View Instant Charts:** Based on your queries, the system will instantly generate visualizations such as bar charts, line charts, heat maps, or combined charts to help you understand the data quickly.\\n\\n5. **Leverage Automatic SQL:** Behind the scenes, Gen BI creates SQL queries with corrected fields to fetch accurate data.\\n\\n6. **Read Summaries:** The system also provides summaries highlighting key trends and anomalies in your data.\\n\\nBy following these steps, you can quickly and intuitively explore your data and get meaningful insights without needing technical expertise.",
  "threadId": "dc9ab8f9-c928-4654-8fa6-b0ef94d45ea5",
  "usage": {
    "taskType": "USER_GUIDE",
    "llmCalls": [
      {
        "step": "intent_classification"
      },
      {
        "step": "user_guide_assistance"
      }
    ]
  }
}

2. allowUserGuide: false — no longer treated as product help. Wren still answers, but from general knowledge and about your data rather than about the product; the built-in guide's material is gone:

{
  "projectId": 1,
  "question": "How do I get started?",
  "allowUserGuide": false
}

{
  "id": "0c9d16b9-c917-4c63-a1f2-eb981243b905",
  "invalidSessionProperties": [],
  "type": "NON_SQL_QUERY",
  "explanation": "To get started with analyzing your e-commerce data, follow these steps:\\n\\n1. Understand your data schema: Review tables like orders, products, customers, payments, and reviews.\\n2. Define your goal: What insights do you want? For example, customer satisfaction, sales trends, or product performance.\\n3. Explore key tables: Start with orders and order_items to see sales details.\\n4. Join related tables: Link orders with customers, products, and reviews for deeper insights.\\n5. Ask specific questions: For example, \\\"Which products have the highest ratings?\\\" or \\\"What is the average delivery time?\\\"\\n\\nBetter questions to ask:\\n- What are the top-selling product categories?\\n- How does payment type affect order completion?\\n- Which cities have the most satisfied customers?",
  "threadId": "3fb73426-ae0a-4e60-857b-aa5636476733",
  "usage": {
    "taskType": "MISLEADING_QUERY",
    "llmCalls": [
      {
        "step": "intent_classification"
      },
      {
        "step": "misleading_assistance"
      }
    ]
  }
}

3. userGuidePrompt — the same question, answered from your guide instead of ours. Note the answer now names your product:

{
  "projectId": 1,
  "question": "How do I get started?",
  "userGuidePrompt": "# Northwind Insights - Help\n\n## Getting started\nOpen **Explore** in the left sidebar and pick a dataset. Type your question in\nthe box at the top; results appear as a table you can switch to a chart.\n\n## Saving a report\nClick **Save** in the top-right of any answer to add it to *My Reports*.\nSaved reports refresh every morning at 06:00 UTC.\n\n## Sharing a report\nOpen a saved report and choose **Share > Copy link**. Links work only for\nteammates in your workspace; external sharing must be enabled by an admin."
}

{
  "id": "589c0e8d-2805-4ff3-81c2-5fba0289c8c2",
  "invalidSessionProperties": [],
  "type": "NON_SQL_QUERY",
  "explanation": "To get started with Northwind Insights, follow these steps:\\n\\n1. Open **Explore** in the left sidebar.\\n2. Pick a dataset that you want to analyze.\\n3. Type your question in the box at the top.\\n4. View the results, which will appear as a table by default.\\n5. You can switch the table view to a chart if you prefer a visual representation.\\n\\nThis will help you begin exploring data and getting insights quickly.",
  "threadId": "c6201f4e-7ae7-4f18-9fae-9d23d2b89dd2",
  "usage": {
    "taskType": "USER_GUIDE",
    "llmCalls": [
      {
        "step": "intent_classification"
      },
      {
        "step": "user_guide_assistance"
      }
    ]
  }
}

Switching product help off removes Wren's product knowledge rather than its willingness to answer — for some phrasings Wren will still respond from general knowledge instead of declining. If you need such questions declined outright, say so in customInstruction — available on /v1/ask, /v1/stream/ask and /v2/stream/ask, but not on the interactive or generate_sql endpoints.

Reading the response

💡
Line breaks inside explanation arrive as the two characters \ and n, not as newline characters — the value contains the literal text \n. Render accordingly. The sql field of a SQL answer is unaffected and carries real newlines.

Your guide replaces the built-in one, it does not extend it

For a request carrying userGuidePrompt the built-in Wren guide is gone. A question your guide does not cover is answered by saying so, rather than from Wren's own documentation — here, "How do I change my account password?" against the guide above:

I have reviewed the user guide provided, but it does not contain information about changing your account password or account management. The guide focuses on using the Northwind Insights tool for data exploration, saving, and sharing reports.

Therefore, I do not find a relevant answer in the user guide to explain how to change your account password. You may need to refer to your platform's account settings or support resources for instructions on password management.

Writing a guide that works

Organize it around tasks. A question that names a task your guide documents ("How do I share a report?") is matched more consistently than a question asking what a term means ("What does the Pulse Score measure?"), even when the guide defines that term.
Response-style directives are followed. Add a section telling Wren how to answer and it applies to the reply. A guide ending in "Always begin your reply with the tag [NW]. Answer in at most two sentences. Never use bullet points or numbered lists." produced exactly that on every question we tried.
Send it on every turn. Ask a follow-up on the same threadId without re-sending userGuidePrompt and that turn falls back to the built-in guide. allowUserGuide behaves the same way — a follow-up without it is classified as product help again.

Combining both fields

allowUserGuide: false wins. When both are sent, product help is off and userGuidePrompt is ignored — nothing from your guide reaches the answer. Send only userGuidePrompt if you want your guide used.