generate_summary

The /generate_summary endpoint takes a user question and a SQL query, executes the SQL, and generates a natural language summary based on the result.

It is typically used after you've already generated or written a SQL query and want to provide an explanation for the data returned.

📘
When to use it

You’ve already written or generated SQL and want a natural summary of the result.

You want to provide a user-friendly explanation in dashboards, chat interfaces, or automated reports.

You need post-processing summarization after raw SQL execution.

For a full pipeline (from question → SQL → result → summary), use the /ask endpoint instead.

How it works

You provide the original natural language question and the sql that was run.
The system runs the query, samples the result (default 500 rows), and generates a user-friendly answer in natural language.
You can customize the sample size and language.

Basic usage

{
  "question": "List the top 5 states with the most customers",
  "sql": "SELECT customer_state, COUNT(*) as customer_count FROM customers GROUP BY customer_state ORDER BY customer_count DESC LIMIT 5"
}

{
  "id": "b2c3d4e5-f6g7-8901-bcde-f23456789012",
  "summary": "São Paulo (SP) leads with 15,847 customers, followed by Rio de Janeiro (RJ) and Minas Gerais (MG). These top 3 states account for over 50% of the customer base.",
  "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.