Converts your question to SQL, runs it, and provides insights about the data
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
The /ask endpoint combines the capabilities of /generate_sql and /generate_summary into a single, intelligent API.
It allows users to ask questions in natural language. If the question can be translated into a SQL query, the system automatically:
- Generates the SQL
- Executes the SQL statement
- Summarizes the result in natural language
If the question is unrelated to the data (e.g., a greeting or product question), the system will return a direct explanation instead.
Want a more interactive experience?If your query takes a bit longer or you want users to see what’s happening behind the scenes, consider using the streaming version (
/stream/ask).
It gives step-by-step updates so users know what stage the system is in — from understanding to SQL generation, execution, and summarization.
Basic Usage
{
"projectId": 1,
"question": "List the top 5 states with the most customers"
}
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"invalidSessionProperties": [],
"sql": "SELECT customer_state, COUNT(*) as customer_count FROM customers GROUP BY customer_state ORDER BY customer_count DESC LIMIT 5",
"summary": "São Paulo (SP) leads with 15,847 customers, followed by Rio de Janeiro (RJ) and Minas Gerais (MG).",
"threadId": "9c537507-9cec-46ed-b877-07bfa6322bed"
}
Non-SQL Query Handling
When a natural language query cannot be converted to SQL, this endpoint delivers a response that explains what the system can help with.
For example:
{
"projectId": 1,
"question": "Hi there"
}{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"invalidSessionProperties": [],
"type": "NON_SQL_QUERY",
"explanation": "I am a data assistant that helps answer questions about your data. You can ask me things like 'Show sales by product.'"
}This typically happens when the query is general, vague, or not related to any known table or data schema.
User Guide Controls
Before answering, Wren classifies what a question is asking for — you can see the step as intent_classification in the response's usage.llmCalls. 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, defaulttrue) — setfalseand 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 whenallowUserGuideisfalse.
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."
}{
"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"
}
]
}
}{
"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"
}
]
}
}usage is abridged above to the two fields that matter here; the real object also carries model names and token counts. usage.taskType and usage.llmCalls[].step name the path that ran. They separate allowUserGuide: false (MISLEADING_QUERY / misleading_assistance) from everything else; a supplied userGuidePrompt reads the same as the built-in guide (USER_GUIDE / user_guide_assistance), because both run the user-guide pipeline.
Conversation Context
You can use the threadId returned in the response to ask follow-up questions while maintaining context:
// Follow-up question
{
"projectId": 1,
"question": "List top 3 instead",
"threadId": "9c537507-9cec-46ed-b877-07bfa6322bed"
}
// Response
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"invalidSessionProperties": [],
"sql": "SELECT customer_state, COUNT(*) as customer_count FROM customers GROUP BY customer_state ORDER BY customer_count DESC LIMIT 3",
"summary": "...",
"threadId": "9c537507-9cec-46ed-b877-07bfa6322bed"
}Error handling
Common Error Codes
NO_DEPLOYMENT_FOUND– No active deployment for the current project.POLLING_TIMEOUT– Timed out while waiting for AI response.INVALID_SQL_ERROR– The generated SQL could not be executed (e.g. due to a schema mismatch).INTERNAL_SERVER_ERROR– An unknown error occurred on the server.
Error example: SQL Generation Fails After Correction
When SQL generation fails during execution (even after internal correction attempts), the API returns:
{
"id": "34f7a6de-b9b8-4c2b-8c6a-ffecebb7b8a2",
"code": "INVALID_SQL_ERROR",
"error": "Column 'customer_namme' does not exist in table 'customers'",
"invalidSql": "SELECT customer_namme FROM customers",
"threadId": "9c537507-9cec-46ed-b877-07bfa6322bed"
}error: The exact error message returned by the database. This often includes syntax issues or column/table name problems.invalidSql: The final SQL statement that failed during execution.
These fields help you:
- Debug the issue more effectively
- Inform the user which part of the query might need adjustment
- Log failures for review or reporting