---
title: "Generate a DuckDB query from a natural-language request"
method: POST
path: "/v4/workflows/{workflowId}/sql"
tags: ["Workflows"]
---

# Generate a DuckDB query from a natural-language request

`POST /v4/workflows/{workflowId}/sql`

## Request

- Base URL: `https://api.kadoa.com`
- URL: `https://api.kadoa.com/v4/workflows/{workflowId}/sql`
- Auth: API key in header `x-api-key`

Generates SQL without executing it. Requires read access to the workflow. Send the selected dataset's columns and up to five sample rows. Ambiguous requests use reasonable defaults explained in the response. A null SQL result explains why the request cannot be answered.

## Path parameters

- `workflowId` string, required

## Request body

- object
  - `prompt` string, required
  - `columns` object[], required
    - `name` string, required
    - `type` string, required
  - `sampleRows` array[], required
    - string[]

## Response `200`

Generated SQL with assumptions, or an explanation of missing data or unsupported requests

- object
  - `sql` string, nullable, required
  - `explanation` string, required

## Other responses

- `400`: Invalid request
- `401`: Unauthorized
- `403`: Access denied
- `404`: Workflow not found
- `413`: Query context is too large
- `429`: Too many SQL requests for this team
- `502`: SQL generation failed
- `503`: SQL generation is not configured

---

[API](https://skmtc.dev/kadoa/apis/kadoa-api.md) · [All operations](https://skmtc.dev/kadoa/apis/kadoa-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kadoa/apis/kadoa-api/revisions/bf7803c927b4?raw)