The /v2/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 /v1/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

{
  "projectId": 1,
  "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.