The POST /v2/stream/ask endpoint lets you ask a single question and stream the whole answer over Server-Sent Events (SSE) — SQL generation and execution state, the streamed natural-language summary (or an explanation for non-SQL questions), and mid-stream clarification checkpoints you can answer without restarting the turn.

This is the v2 (adhoc) streaming ask — the successor to the v1 /stream/ask. Two things are intentionally different from v1:

• Charts are not part of this stream. Once you have the generated SQL, render a chart separately with POST /v2/generate_chart (Apache ECharts).
• Clarification is built in. When the AI needs input, the stream emits a pendingQuestion frame; you answer it with POST /v2/stream/ask/respond and the same open stream resumes.

What It Does

The endpoint returns a Server-Sent Events (SSE) stream that includes:

1. A leading init frame carrying the threadId (use it for follow-ups).
2. Processing state for SQL generation (understanding → searching → planning → generating → correcting) and execution.
3. The generated SQL and, for SQL answers, a streamed natural-language summary_generation content block — or, for non-SQL questions, a streamed explanation content block.
4. pendingQuestion frames when the AI pauses for clarification at the intent or sql_reasoning checkpoint.

Basic Usage

{
  "projectId": 1,
  "question": "List the top 5 states with the most customers"
}

This simplified stream shows the key phases of a /v2/stream/ask request — from the leading init frame, through understanding and generating SQL, executing it, and finally producing a streamed summary.

// Stream begins
data: { "type": "init", "threadId": "0625991d-1bba-407d-8ad4-dd0210172484", "queryId": null }

data: { "type": "message_start" }

// SQL Generation Stages
data: { "type": "state", "data": { "state": "sql_generation_start" }}
data: { "type": "state", "data": { "state": "sql_generation_understanding" }}
data: { "type": "state", "data": { "state": "sql_generation_searching" }}
data: { "type": "state", "data": { "state": "sql_generation_planning" }}
data: { "type": "state", "data": { "state": "sql_generation_generating" }}
data: { "type": "state", "data": { "state": "sql_generation_success", "sql": "SELECT ... LIMIT 5" }}

// SQL Execution
data: { "type": "state", "data": { "state": "sql_execution_start" }}
data: { "type": "state", "data": { "state": "sql_execution_end" }}

// Summary Generation (streamed content block)
data: { "type": "content_block_start", "content_block": { "type": "text", "name": "summary_generation" }}
data: { "type": "content_block_delta", "delta": { "text": "Here" }}
data: { "type": "content_block_delta", "delta": { "text": " are" }}
data: { "type": "content_block_delta", "delta": { "text": " the top 5 states by customer count." }}
data: { "type": "content_block_stop" }

// Stream ends
data: { "type": "message_stop" }

This example omits several detailed properties (such as question, rephrasedQuestion, intentReasoning, traceId, and timestamp) for clarity. Refer to the full schema for a complete breakdown of all available fields.

Request fields

Single-active-turn guard. When you supply a threadId, a second concurrent /v2/stream/ask for the same thread is rejected with 409 (A turn is already in progress for this thread). Omit threadId and the server generates one (returned in the init frame).

User Guide Controls

Before answering, Wren classifies what a question is asking for. Most questions are about the data and become SQL. Some are not: "Do I need to know SQL?", "How do I get started?" Wren recognises those as product help and answers them from a built-in user guide describing Wren itself.

If you have embedded Wren in your own product that is usually the wrong answer — your users have never heard of Wren, and the guide describes our product rather than yours. Two per-request fields change it:

• allowUserGuide (boolean, default true) — set false and product help is removed from classification altogether. The question is classified as something else and the built-in guide is never consulted.
• userGuidePrompt (string) — supply your own guide and Wren uses it in place of ours, both when classifying the question and when answering it. Ignored when allowUserGuide is false.

Both default to today's behavior, so omitting them leaves the request unchanged. Both are per-request: re-send them on every turn of a thread. See User Guide Controls for the shared behaviour, including what happens to a question your guide does not cover.

Switch the built-in guide off:

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

Or answer from your own guide instead — same question, your content:

{
  "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."
}

The answer streams as an explanation content block.

Frames below are real but abridged — the stream opens with init, message_start and three SQL-generation state frames that are not shown, and the token-by-token text_delta frames are collapsed. The complete streamed text follows each block, with the literal \n sequences rendered as line breaks.

data: {"type":"content_block_start","content_block":{"type":"text","name":"explanation"},"timestamp":1788000689141}

data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"To"},"timestamp":1788000689142}

data: {"type":"content_block_delta","delta":{"type":"text_delta","text":" get"},"timestamp":1788000689143}

// ... 153 more text_delta frames ...

data: {"type":"content_block_stop","timestamp":1788000689229}

data: {"type":"message_stop","data":{"threadId":"05cef683-22d8-4cf8-a562-444dc2f804cc","duration":3124},"timestamp":1788000689231}

To get started with analyzing your e-commerce data, follow these steps:

1. Understand your data schema: Review tables like orders, products, customers, payments, and reviews.
2. Define your goal: What insights do you want? For example, customer satisfaction, sales trends, or product performance.
3. Explore key tables: Start with orders and reviews to analyze sales and customer feedback.
4. Join related tables: Combine orders with payments, products, and sellers for deeper insights.
5. Ask specific questions: For example, "Which products have the highest ratings?" or "What is the average delivery time?"

Better questions to ask:

• What are the top-selling product categories?
• How does payment type affect order completion?
• Which regions have the most satisfied customers?

data: {"type":"content_block_start","content_block":{"type":"text","name":"explanation"},"timestamp":1788000701720}

data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"To"},"timestamp":1788000701721}

data: {"type":"content_block_delta","delta":{"type":"text_delta","text":" get"},"timestamp":1788000701722}

// ... 87 more text_delta frames ...

data: {"type":"content_block_stop","timestamp":1788000701771}

data: {"type":"message_stop","data":{"threadId":"3fc4ff3e-9f23-49b6-8a75-9968597a266b","duration":3089},"timestamp":1788000701773}

To get started with Northwind Insights, follow these steps:

1. Open Explore in the left sidebar.
2. Pick a dataset that you want to analyze.
3. Type your question in the box at the top.
4. View the results, which will appear as a table by default.
5. You can switch the table view to a chart if you prefer a visual representation.

This will help you begin exploring your data easily.

This endpoint sends no usage object — its message_stop carries only threadId and duration — so the streamed text is the only signal. The v1 /stream/ask does report usage there.

Clarification (pendingQuestion → respond)

At the intent or sql_reasoning checkpoint the AI may need you to disambiguate. Instead of failing, the stream emits a pendingQuestion frame and keeps the connection open:

data: {
  "type": "pendingQuestion",
  "data": {
    "questionId": "b8f0c1e2-...",
    "checkpoint": "intent",
    "question": "Which \"customers\" did you mean?",
    "options": [
      { "value": "all", "label": "All registered customers" },
      { "value": "active", "label": "Only active customers" }
    ],
    "selectionType": "single",
    "rationale": "The question is ambiguous about customer status.",
    "queryId": "1f0a3c7d-...",
    "threadId": "0625991d-1bba-407d-8ad4-dd0210172484"
  },
  "timestamp": 1751014955000
}

Answer it with a separate call to POST /v2/stream/ask/respond, carrying the queryId and questionId from the frame. This call returns immediately ({ "status": "accepted" }); the ask resumes on the same open SSE stream — you do not reopen /v2/stream/ask.

{
  "projectId": 1,
  "queryId": "1f0a3c7d-...",
  "questionId": "b8f0c1e2-...",
  "action": "SUBMIT",
  "answers": ["active"],
  "threadId": "0625991d-1bba-407d-8ad4-dd0210172484"
}

action is case-insensitive. See the stream/ask/respond reference for the full request/response contract and error codes.

State Lifecycle

graph TD
  init["init"]
  message_start["message_start"]
  sql_start["sql_generation_start"]
  sql_understanding["sql_generation_understanding"]
  sql_searching["sql_generation_searching"]
  sql_planning["sql_generation_planning"]
  sql_generating["sql_generation_generating"]
  sql_correcting["sql_generation_correcting"]
  sql_success["sql_generation_success"]
  sql_failed["sql_generation_failed"]
  sql_stopped["sql_generation_stopped"]

  sql_exec_start["sql_execution_start"]
  sql_exec_end["sql_execution_end"]

  pending["pendingQuestion (intent / sql_reasoning)"]
  respond["POST /v2/stream/ask/respond"]

  summary_start["content_block_start: summary_generation"]
  summary_streaming["content_block_delta (text)"]
  summary_stop["content_block_stop"]

  explanation_block["content_block_*: explanation (non-SQL)"]

  error_event["type: error"]
  message_stop["message_stop"]

  %% Normal flow
  init --> message_start -->|"Trigger SQL generation"| sql_start
  sql_start --> sql_understanding --> sql_searching --> sql_planning --> sql_generating

  sql_generating -->|"Auto-correct (if needed)"| sql_correcting
  sql_correcting --> sql_success
  sql_generating --> sql_success

  sql_success -->|"Run SQL"| sql_exec_start --> sql_exec_end

  sql_exec_end -->|"Start LLM summary"| summary_start
  summary_start --> summary_streaming --> summary_stop --> message_stop

  %% Non-SQL branch
  sql_understanding -->|"Non-SQL question"| explanation_block --> message_stop

  %% Clarification checkpoints (resume on the same open stream)
  sql_understanding -.->|"Intent checkpoint"| pending
  sql_generating -.->|"SQL-reasoning checkpoint"| pending
  pending -.->|"Answer via respond"| respond
  respond -.->|"Turn resumes"| sql_generating

  %% Error flows
  sql_generating -->|"Too many corrections failed"| sql_failed -->|"Emit error event"| error_event --> message_stop
  sql_generating -->|"User canceled"| sql_stopped --> message_stop
  sql_exec_start -->|"SQL execution error"| error_event --> message_stop
  summary_start -->|"LLM failed to summarize"| error_event --> message_stop

Event Types

During a /v2/stream/ask request, the API streams a sequence of events using Server-Sent Events (SSE). Each event provides insight into the system’s current state or output.

init

• Purpose: Leading frame of every stream. Delivers the threadId to use for follow-ups.
• Payload: queryId is always null here — the per-turn queryId used to answer clarifications is delivered with each pendingQuestion frame instead.

{
  "type": "init",
  "threadId": "0625991d-1bba-407d-8ad4-dd0210172484",
  "queryId": null
}

message_start

• Purpose: Indicates the start of a new streaming response.
• Payload: Contains the timestamp when the process began.

{
  "type": "message_start",
  "timestamp": 1751014954139
}

state

• Purpose: Describes what stage the system is in during processing.

State Lifecycle Overview

data Field Reference ("type": "state")

🔹 sql_generation_start

🔹 SQL Generation In-Progress States
(e.g., sql_generation_understanding, searching, planning, generating, correcting)

🔹 sql_generation_success

🔹 sql_execution_start

🔹 sql_execution_end

Example

data: {
  "type": "state",
  "data": {
    "state": "sql_generation_start",
    "question": "list 5 customers",
    "threadId": "0625991d-1bba-407d-8ad4-dd0210172484",
    "language": "English"
  },
  "timestamp": 1751014954142
}

data: {
  "type": "state",
  "data": {
    "state": "sql_generation_understanding",
    "pollCount": 1,
    "rephrasedQuestion": null,
    "intentReasoning": null,
    "sqlGenerationReasoning": null,
    "retrievedTables": null,
    "invalidSql": null,
    "traceId": "f218b1f7-4623-4a56-8b66-18d544797b20"
  },
  "timestamp": 1751014954165
}

data: {
  "type": "state",
  "data": {
    "state": "sql_generation_searching",
    "pollCount": 4,
    "rephrasedQuestion": "List 5 customers from the olist_customers_dataset table.",
    "intentReasoning": "User wants to retrieve specific customer data, likely using SQL query.",
    "sqlGenerationReasoning": null,
    "retrievedTables": null,
    "invalidSql": null,
    "traceId": "f218b1f7-4623-4a56-8b66-18d544797b20"
  },
  "timestamp": 1751014957183
}

data: {
  "type": "state",
  "data": {
    "state": "sql_generation_planning",
    "pollCount": 6,
    "rephrasedQuestion": "List 5 customers from the olist_customers_dataset table.",
    "intentReasoning": "User wants to retrieve specific customer data, likely using SQL query.",
    "sqlGenerationReasoning": null,
    "retrievedTables": ["olist_customers_dataset"],
    "invalidSql": null,
    "traceId": "f218b1f7-4623-4a56-8b66-18d544797b20"
  },
  "timestamp": 1751014959232
}

data: {
  "type": "state",
  "data": {
    "state": "sql_generation_generating",
    "pollCount": 9,
    "rephrasedQuestion": "List 5 customers from the olist_customers_dataset table.",
    "intentReasoning": "User wants to retrieve specific customer data, likely using SQL query.",
    "sqlGenerationReasoning": "1. **Identify the table involved**: The question asks for customer data, so the relevant table is `olist_customers_dataset`.\n\n2. **Determine the number of records needed**: The user requests 5 customers, so we need to select 5 entries from the table.",
    "retrievedTables": ["olist_customers_dataset"],
    "invalidSql": null,
    "traceId": "f218b1f7-4623-4a56-8b66-18d544797b20"
  },
  "timestamp": 1751014962254
}

data: {
  "type": "state",
  "data": {
    "state": "sql_generation_success",
    "sql": "SELECT \"o\".\"customer_id\", \"o\".\"customer_zip_code_prefix\", \"o\".\"customer_city\", \"o\".\"customer_state\" FROM \"olist_customers_dataset\" AS \"o\" LIMIT 5"
  },
  "timestamp": 1751014963263
}

data: {
  "type": "state",
  "data": {
    "state": "sql_execution_start",
    "sql": "SELECT \"o\".\"customer_id\", \"o\".\"customer_zip_code_prefix\", \"o\".\"customer_city\", \"o\".\"customer_state\" FROM \"olist_customers_dataset\" AS \"o\" LIMIT 5"
  },
  "timestamp": 1751014963263
}

data: {
  "type": "state",
  "data": {
    "state": "sql_execution_end"
  },
  "timestamp": 1751014963339
}

content_block_start

• Purpose: Signals the beginning of a streamed text block. The name tells you which one:
  • summary_generation — a natural-language summary of the SQL result.
  • explanation — a natural-language answer to a non-SQL question (no SQL is generated in this case).
• Payload: Describes the block (always type: "text").

{
  "type": "content_block_start",
  "content_block": {
    "type": "text",
    "name": "summary_generation"
  }
}

content_block_delta

• Purpose: Streams the actual content in parts (e.g., the summary or explanation, chunk by chunk).
• Payload: Includes a text_delta with the partial content.

{
  "type": "content_block_delta",
  "delta": {
    "type": "text_delta",
    "text": "São Paulo (SP) leads with"
  }
}

content_block_stop

• Purpose: Indicates the end of a streamed content block.

{
  "type": "content_block_stop"
}

pendingQuestion

• Purpose: The AI paused at a clarification checkpoint and needs your input before continuing. The stream stays open; answer via POST /v2/stream/ask/respond.
• Payload:

{
  "type": "pendingQuestion",
  "data": {
    "questionId": "b8f0c1e2-1a2b-4c3d-9e8f-7a6b5c4d3e2f",
    "checkpoint": "intent",
    "question": "Which \"customers\" did you mean?",
    "options": [
      { "value": "all", "label": "All registered customers" },
      { "value": "active", "label": "Only active customers" }
    ],
    "selectionType": "single",
    "rationale": "The question is ambiguous about customer status.",
    "queryId": "1f0a3c7d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
    "threadId": "0625991d-1bba-407d-8ad4-dd0210172484"
  },
  "timestamp": 1751014955000
}

message_stop

• Purpose: Marks the end of the entire stream. Includes processing duration (ms) and threadId.

{
  "type": "message_stop",
  "data": {
    "threadId": "0625991d-1bba-407d-8ad4-dd0210172484",
    "duration": 11096
  }
}

Error Handling

If an error occurs at any stage of the pipeline, the server emits a type: "error" frame (followed by a terminal message_stop). This lets clients gracefully detect and handle failures — e.g., show an error message in the UI, add retry logic, or cancel streaming.

Error Event Structure

{
  "type": "error",
  "data": {
    "code": "INVALID_SQL_ERROR",
    "error": "Unrecognized token near FROM"
  },
  "timestamp": 1751015028888
}

Additional context fields (such as traceId) may accompany data depending on the error.

Pre-stream errors. Validation failures that happen before the SSE stream opens are returned as a normal JSON error response instead of an error frame — 400 (missing projectId/question), 401 (invalid API key), 404 (project not found), or 409 (a turn is already in progress for this thread).