ask

POST https://example.com/api/v1/ask

Converts your question to SQL, runs it, and provides insights about the data

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:

1. Generates the SQL
2. Executes the SQL statement
3. 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

Request

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

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "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:

Request

{
  "question": "Hi there"
}

Response

{  
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "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.

Conversation Context

You can use the threadId returned in the response to ask follow-up questions while maintaining context:

JavaScript

// Follow-up question
{
  "question": "List top 3 instead",
  "threadId": "9c537507-9cec-46ed-b877-07bfa6322bed"
}

// Response
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "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:

Invalid SQL Error

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