stream/interactive

Time	Status	User Agent
Retrieving recent requests…

Streams interactive mode conversations with real-time AI responses and conversation management

This endpoint enables natural, conversational interactions with your data. Unlike the standard /stream/ask endpoint which focuses on SQL generation and execution, interactive mode allows the AI to engage in a more flexible conversation flow — it may ask clarifying questions, provide explanations, generate insights, or create visualizations based on the context.

This endpoint combines conversation creation and streaming into a single POST request, making it ideal for building conversational interfaces, chatbots, or interactive data exploration tools.

What It Does

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

Conversation events — Real-time AI responses, explanations, and content blocks as they are generated.
Conversation history management — Automatic thread management for multi-turn conversations.
Content blocks — Various types of content including text explanations, SQL queries, charts, and recommended actions.

Basic Usage

Initial Question

Request

{
  "projectId": 123,
  "question": "What are the top 5 states with the most customers?"
}

Response

The stream begins immediately after validation and authentication. Events are forwarded directly from the AI Service:

// Stream begins - events forwarded from AI Service
event: message_start
data: {"type":"message_start","message":{"query_id":"6771808b-790a-48f3-b60c-5c7e62a694f4","trace_id":"a87102f7-6e27-4aed-a32d-52b444ceadac"}}

event: content_block_start
data: {"type":"content_block_start","index":0,"message":{"type":"text","content_block_label":"GREETINGS","trace_id":"a87102f7-6e27-4aed-a32d-52b444ceadac","metadata":{"visible_in_ui":true,"ui_components":["MARKDOWN","ASSISTANT"],"show_elapsed_time":false,"elapsed_time":0.0}}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"message":{"type":"text_delta","content_block_label":"GREETINGS","content":"You're all set. Let me process that for you.","trace_id":"a87102f7-6e27-4aed-a32d-52b444ceadac","metadata":{"visible_in_ui":true,"ui_components":["MARKDOWN","ASSISTANT"],"show_elapsed_time":false,"elapsed_time":0.01}}}

event: content_block_stop
data: {"type":"content_block_stop","index":0,"message":{"type":"text","trace_id":"a87102f7-6e27-4aed-a32d-52b444ceadac","content_block_label":"GREETINGS","metadata":{"show_elapsed_time":false,"elapsed_time":0.01}}}


...

// Stream ends
data: {"done": true}

Follow-up Question

Request

{
  "projectId": 123,
  "threadId": "0625991d-1bba-407d-8ad4-dd0210172484",
  "question": "What about last month?"
}

When threadId is provided, the API automatically retrieves conversation history and includes it in the request to the AI Service, enabling context-aware responses.

Response

Same SSE stream format as initial question, with AI responses considering previous conversation context.

Request Parameters

Parameter	Type	Required	Description
`projectId`	number	Yes	The ID of the project to query
`question`	string	Yes	The user's question or message
`threadId`	string	No	Thread ID for follow-up questions. If not provided, a new thread is created automatically
`language`	string	No	Language code for responses (e.g., "en", "zh"). Defaults to project language

Response Format

The endpoint returns a Server-Sent Events (SSE) stream with Content-Type: text/event-stream.

Stream Events

Events are forwarded directly from the AI Service's conversation API. The following event types are supported:

message_start — Indicates the start of a new conversation response
content_block_start — Beginning of a content block
content_block_delta — Streaming content updates (text or JSON deltas)
content_block_stop — End of a content block
content_block_failed — Indicates a content block failed to generate
message_stop — End of the entire message stream
error — Error events

Completion Event

When the stream completes successfully, the API sends a final event:

{
  "done": true
}

This event is sent by the API wrapper, not the AI Service, to indicate that streaming has finished.

Event Types

message_start

Indicates the start of a new conversation response.

Example

{
  "type": "message_start",
  "message": {
    "query_id": "6771808b-790a-48f3-b60c-5c7e62a694f4",
    "trace_id": "a87102f7-6e27-4aed-a32d-52b444ceadac"
  }
}

Fields

Field	Type	Description
`query_id`	string	Unique identifier for this conversation query
`trace_id`	string	Trace ID for backend debugging

content_block_start

Signals the beginning of a content block.

Example

{
  "type": "content_block_start",
  "index": 0,
  "message": {
    "type": "text",
    "content_block_label": "GREETINGS",
    "trace_id": "a87102f7-6e27-4aed-a32d-52b444ceadac",
    "metadata": {
      "visible_in_ui": true,
      "ui_components": ["MARKDOWN", "ASSISTANT"],
      "show_elapsed_time": false,
      "elapsed_time": 0.0
    }
  }
}

Fields

Field	Type	Description
`index`	number	Index of the content block in the message
`message.type`	string	Content type: `"text"`, `"tool_use"`, or `"think"`
`message.content_block_label`	string	Label identifying the content block type (see Content Block Labels below)
`message.trace_id`	string	Trace ID for debugging
`message.metadata`	object	Metadata including UI components, visibility, and timing

content_block_delta

Streams incremental content updates from the AI. Can contain either text deltas or JSON deltas.

Example (Text Delta)

{
  "type": "content_block_delta",
  "index": 0,
  "message": {
    "type": "text_delta",
    "content_block_label": "GREETINGS",
    "content": "You're all set. Let me process that for you.",
    "trace_id": "a87102f7-6e27-4aed-a32d-52b444ceadac",
    "metadata": {
      "visible_in_ui": true,
      "ui_components": ["MARKDOWN", "ASSISTANT"],
      "show_elapsed_time": false,
      "elapsed_time": 0.01
    }
  }
}

Example (JSON Delta)

{
  "type": "content_block_delta",
  "index": 1,
  "message": {
    "type": "json_delta",
    "content_block_label": "SQL_GENERATION",
    "content": {
      "success":true,
      "sql":"SELECT ..."
		},
    "trace_id": "a87102f7-6e27-4aed-a32d-52b444ceadac",
    "metadata": {
      "visible_in_ui": true,
      "ui_components": ["PREPARATION"],
      "show_elapsed_time": true,
      "elapsed_time": 2.5
    }
  }
}

content_block_stop

Indicates the end of a content block.

Example

{
  "type": "content_block_stop",
  "index": 0,
  "message": {
    "type": "text",
    "trace_id": "a87102f7-6e27-4aed-a32d-52b444ceadac",
    "content_block_label": "GREETINGS",
    "metadata": {
      "show_elapsed_time": false,
      "elapsed_time": 0.01
    }
  }
}

content_block_failed

Indicates that a content block failed to generate.

Example

{
  "type": "content_block_failed",
  "index": 1,
  "message": {
    "type": "json_failed",
    "content_block_label": "SQL_GENERATION",
    "content": "Error message",
    "trace_id": "a87102f7-6e27-4aed-a32d-52b444ceadac",
    "metadata": {
      "visible_in_ui": true,
      "ui_components": ["PREPARATION"],
      "show_elapsed_time": true,
      "elapsed_time": 5.0
    }
  }
}

message_stop

Marks the end of the entire message stream.

Example

{
  "type": "message_stop",
  "message": {
    "query_id": "6771808b-790a-48f3-b60c-5c7e62a694f4",
    "trace_id": "a87102f7-6e27-4aed-a32d-52b444ceadac"
  }
}

error

Error events indicate failures during processing.

Example

{
  "type": "error",
  "message": {
    "query_id": "6771808b-790a-48f3-b60c-5c7e62a694f4",
    "trace_id": "a87102f7-6e27-4aed-a32d-52b444ceadac",
    "code": "SQL_GENERATION_FAILED",
    "message": "Failed to generate SQL",
    "invalid_sql": "SELECT * FROM invalid_table",
    "metadata": {
      "ui_components": ["ERROR"],
      "visible_in_ui": true
    }
  }
}

Content Block Labels

The content_block_label field identifies the type of content being streamed. The following labels are supported:

Text-Based Content Blocks

These blocks stream text content incrementally:

GREETINGS — Initial greeting messages
MISLEADING_QUERY_ASSISTANCE — Assistance for misleading queries
GENERAL_ASSISTANCE — General help and guidance
USER_GUIDE_ASSISTANCE — User guide and documentation assistance
DATA_EXPLORATION_ASSISTANCE — Data exploration guidance
USER_CLARIFICATION_ASSISTANCE — Requests for user clarification
SQL_GENERATION_REASONING — Reasoning behind SQL generation
SQL_ANSWER — Final answer with SQL results
CHART_SUMMARY — Summary of chart generation
FAILED_CONTENT_BLOCK_RENDERING — Error messages when content blocks fail

Structured Content Blocks

These blocks contain structured JSON data:

`HISTORICAL_QUESTION_RETRIEVAL`

Contains SQL from historical questions.

{
  "sql": "SELECT ...",
  "type": "view",
  "viewId": "optional-view-id"
}

`SQL_PAIRS_RETRIEVAL`

Contains retrieved SQL pairs from knowledge base.

{
  "sql_pairs": [
    {
      "question": "What are the top products?",
      "sql": "SELECT ..."
    }
  ]
}

`INSTRUCTIONS_RETRIEVAL`

Contains retrieved instructions from knowledge base.

{
  "instructions": [
    {
      "instruction": "Always use UTC timezone",
      "question": "What time is it?",
      "instruction_id": "inst-123"
    }
  ]
}

`INTENT_CLASSIFICATION`

Classifies user intent and provides reasoning.

{
  "intent": "TEXT_TO_SQL",
  "rephrased_question": "Show me sales data",
  "reasoning": "User wants to query sales data using SQL"
}

Intent Types:

MISLEADING_QUERY
TEXT_TO_SQL
GENERAL
USER_GUIDE
DATA_EXPLORATION
CHART
USER_CLARIFICATION

`DB_SCHEMA_RETRIEVAL`

Contains retrieved database schema information.

Success:

{
  "success": true,
  "retrieved_tables": ["customers", "orders", "products"]
}

Failure:

{
  "success": false,
  "error": {
    "code": "NO_RELEVANT_DATA",
    "message": "No relevant tables found"
  }
}

`SQL_GENERATION`

Contains generated SQL query.

Success:

{
  "success": true,
  "sql": "SELECT customer_id, SUM(amount) FROM orders GROUP BY customer_id"
}

Failure:

{
  "success": false,
  "error": {
    "code": "GENERATION_FAILED",
    "message": "Unable to generate SQL"
  }
}

`SQL_DIAGNOSIS`

Contains diagnosis reasoning for SQL issues.

{
  "reasoning": "The SQL query failed because table 'invalid_table' does not exist"
}

`SQL_CORRECTION`

Contains corrected SQL after diagnosis.

Success:

{
  "success": true,
  "sql": "SELECT * FROM valid_table"
}

Failure:

{
  "success": false,
  "error": {
    "code": "CORRECTION_FAILED",
    "message": "Unable to correct SQL"
  }
}

`SQL_EXECUTOR`

Indicates SQL execution status.

Success:

{
  "success": true
}

Failure:

{
  "success": false,
  "error": {
    "code": "QUERY_FAILED",
    "message": "SQL execution failed"
  }
}

`FIX_SQL`

Contains SQL fix information.

{
  "data": {
    "code": "NO_RELEVANT_SQL",
    "message": "No relevant SQL found",
    "invalid_sql": "SELECT * FROM invalid_table"
  }
}

`CHART_INTENT_CLASSIFICATION`

Classifies chart intent.

Success:

{
  "success": true,
  "reasoning": ""
}

Failure:

{
  "success": false,
  "reasoning": "Unable to determine chart intent"
}

`CHART_TYPE_RECOMMENDATION`

Recommends chart type.

Success:

{
  "success": true,
  "reasoning": ""
}

Failure:

{
  "success": false,
  "reasoning": "Unable to recommend chart type"
}

`CHART_VALIDATION`

Validates chart generation.

Success:

{
  "success": true,
  "reasoning": ""
}

Failure:

{
  "success": false,
  "reasoning": "Chart validation failed"
}

`CHART_GENERATION`

Contains generated chart schema.

{
  "chart_schema": {
    "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
    "data": {...},
    "mark": "bar",
    "encoding": {...}
  }
}

`CHART_ADJUSTMENT`

Contains adjusted chart schema.

{
  "chart_schema": {
    "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
    "data": {...},
    "mark": "line",
    "encoding": {...}
  }
}

`DATA_PREVIEW`

Contains data preview information.

Chart Preview:

{
  "type": "CHART",
  "payload": {
    "title": "Sales Chart",
    "sql": "SELECT ...",
    "chart_schema": {...}
  }
}

Table Preview:

{
  "type": "TABLE",
  "payload": {
    "title": "Sales Data",
    "sql": "SELECT ..."
  }
}

SQL Preview:

{
  "type": "SQL",
  "payload": {
    "title": "Generated SQL",
    "sql": "SELECT ..."
  }
}

`INSTRUCTION_RECOMMENDATION`

Contains recommended instructions.

{
  "instruction_recommendation_info": [
    {
      "uuid": "rec-123",
      "instruction_type": "SQL_PAIR",
      "instruction": "Use customer_id for joins",
      "human_readable_explanation": "This will improve query performance"
    }
  ]
}

`RECOMMENDED_ACTIONS`

Contains recommended follow-up actions.

{
  "actions": [
    {
      "label": "Show me last month",
      "template": "What about last month?"
    }
  ]
}

AI_EVENT_COST

⚠️ Note: This event is for internal usage within the WrenAI system only and is used for monitoring and analysis purposes. It does not directly correspond to the actual usage or charges billed to you, and should not be treated as a representation of your final cost.

Non-Chargeable Events

The following events do not result in credit charges:

NO_DB_SCHEMAS
SQL_TIMEOUT
SQL_PERMISSION_DENIED
SQL_CORRCTION_FAILED
SQL_QUERY_ALL_FAILED
CHART_INTENT_FAILED
CHART_TYPE_FAILED
CHART_FAILED
OTHERS

CONVERSATION_HISTORY_PAYLOAD

Contains the conversation history payload for persistence. This is used internally to maintain conversation context and is included in API history.

Structure

The structure varies depending on the conversation type and content generated. The request object always contains the user's query, while response contains different fields based on what was generated.

Example 1: SQL Query Response

{
  "type": "content_block_delta",
  "message": {
    "type": "json_delta",
    "content_block_label": "CONVERSATION_HISTORY_PAYLOAD",
    "content": {
      "request": {
        "query": "What are the top 5 products?"
      },
      "response": {
        "sql": "SELECT product_id, SUM(quantity) FROM orders GROUP BY product_id LIMIT 5",
        "sql_reasoning": "Aggregating order quantities by product",
        "text": "Here are the top 5 products by quantity sold..."
      }
    }
  }
}

Example 2: Chart Response

{
  "type": "content_block_delta",
  "message": {
    "type": "json_delta",
    "content_block_label": "CONVERSATION_HISTORY_PAYLOAD",
    "content": {
      "request": {
        "query": "how many data do i have in events, please draw me a chart"
      },
      "response": {
        "intent": "CHART",
        "sql": "SELECT COUNT(*) AS \"row_count\" FROM \"events\"",
        "sql_reasoning": null,
        "text": null,
        "chart_schema": {
          "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
          "title": "Row count in events table",
          "mark": {"type": "text", "tooltip": true},
          "encoding": {...},
          "data": {"values": []},
          "width": 320,
          "height": 320
        },
        "metadata": {
          "failed_sql": null
        }
      }
    }
  }
}

Fields

Field	Type	Description
`request.query`	string	The user's question
`response.intent`	string (optional)	Intent classification (e.g., "CHART", "TEXT_TO_SQL")
`response.sql`	string (optional)	Generated SQL query, if applicable
`response.sql_reasoning`	string (optional)	Reasoning behind SQL generation
`response.text`	string (optional)	Text explanation or answer
`response.chart_schema`	object (optional)	Chart schema (Vega-Lite specification) if a chart was generated
`response.metadata`	object (optional)	Additional metadata (e.g., `failed_sql`)

Note: All fields in response are optional. The structure varies based on the conversation type and what content was generated. Only relevant fields are included.

What It Does

Basic Usage

Initial Question

Follow-up Question

Request Parameters

Response Format

Stream Events

Completion Event

Event Types

message_start

content_block_start

content_block_delta

content_block_stop

content_block_failed

message_stop

error

Content Block Labels

Text-Based Content Blocks

Structured Content Blocks

HISTORICAL_QUESTION_RETRIEVAL

SQL_PAIRS_RETRIEVAL

INSTRUCTIONS_RETRIEVAL

INTENT_CLASSIFICATION

DB_SCHEMA_RETRIEVAL

SQL_GENERATION

SQL_DIAGNOSIS

SQL_CORRECTION

SQL_EXECUTOR

FIX_SQL

CHART_INTENT_CLASSIFICATION

CHART_TYPE_RECOMMENDATION

CHART_VALIDATION

CHART_GENERATION

CHART_ADJUSTMENT

DATA_PREVIEW

INSTRUCTION_RECOMMENDATION

RECOMMENDED_ACTIONS

AI_EVENT_COST

CONVERSATION_HISTORY_PAYLOAD

200Server-sent events stream

400Bad request - Invalid request parameters or no deployment found

401Unauthorized - Invalid or missing API key

404Project or thread not found

409Conflict - Concurrent request on same thread

500Internal server error

`HISTORICAL_QUESTION_RETRIEVAL`

`SQL_PAIRS_RETRIEVAL`

`INSTRUCTIONS_RETRIEVAL`

`INTENT_CLASSIFICATION`

`DB_SCHEMA_RETRIEVAL`

`SQL_GENERATION`

`SQL_DIAGNOSIS`

`SQL_CORRECTION`

`SQL_EXECUTOR`

`FIX_SQL`

`CHART_INTENT_CLASSIFICATION`

`CHART_TYPE_RECOMMENDATION`

`CHART_VALIDATION`

`CHART_GENERATION`

`CHART_ADJUSTMENT`

`DATA_PREVIEW`

`INSTRUCTION_RECOMMENDATION`

`RECOMMENDED_ACTIONS`