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.