The /stream_explanation endpoint provides detailed explanations for non-SQL queries through server-sent events. When a natural language query cannot be converted to SQL, this endpoint delivers a streaming response that explains what the system can help with.

Basic Usage

To receive a streaming explanation, use the explanationQueryId received from a previous /generate_sql request that returned a NON_SQL_QUERY error:

Response Format

The response is a text/event-stream with each event containing a JSON message. The content is streamed in small chunks to provide a responsive experience:

data: {"message":"Wren AI is "}

data: {"message":"designed to "}

data: {"message":"help you analyze "}

data: {"message":"your data with "}

data: {"message":"natural language queries. I can "}

data: {"message":"provide insights about "}

data: {"message":"your business data and "}

data: {"message":"create visualizations."}

data: {"done":true}

Client-Side Handling

When consuming this stream:

Parse each event's data as JSON
For messages with the message property:
- Append the text to your UI
- Update display incrementally as fragments arrive
When you receive {"done":true}, the explanation is complete

Error Handling

If the stream fails or the query ID is invalid, you'll receive a 500 status code with an error message.

Common errors include:

Invalid query ID
Expired explanation (explanations may expire after a certain time period)
Server processing issues

Always implement error handling to gracefully manage connection issues or invalid requests.

200Stream of explanation events

401Unauthorized

403Forbidden - Project access denied

500Internal server error