---
title: "Text-to-SQL (NSQL)"
method: POST
path: "/v1/nsql"
tags: ["SQL"]
---

# Text-to-SQL (NSQL)

`POST /v1/nsql`

Generate and optionally execute a natural-language text-to-SQL (NSQL) query.

This endpoint generates a SQL query using a natural language query (NSQL) and optionally executes it.
The SQL query is generated by the specified model and executed if the `Accept` header is not set to `application/sql`.
When `stream` is true, the response is streamed as Server-Sent Events (SSE).

## Headers

- `Accept` string, required

## Request body

- Request
  - `datasets` string[], nullable — Names of datasets to sample from when constructing model context; this is a sampling hint and does not restrict which tables queries can target. If omitted, all datasets are used.
  - `model` string, nullable — The name of the model to use for SQL generation. If omitted, Spice defaults to the only compatible LLM model configured in the Spicepod.
  - `prompt_cache_key` string, nullable — Stable prompt-cache key forwarded to the configured NSQL model for provider-specific cache handling.
  - `query` string, required — The natural language query to be converted into SQL
  - `sample_data_enabled` boolean — Whether sample data is included in the context for SQL generation. Default: false
  - `stream` boolean — If true, streams the response instead of waiting for completion

## Response `200`

SQL query executed successfully

- unknown[]
  - unknown

## Other responses

- `400` — Invalid request parameters
- `500` — Internal server error

## Changes

> 53 revisions in range; 26 could not be searched.

- **2025-03-18** `dd94571fef79` — 4 breaking, 2 warning
  - the request property `model` became not nullable
  - removed the media type `application/sql` for the response with the status `200`
  - removed the media type `application/vnd.spiceai.nsql.v1+json` for the response with the status `200`
  - removed the media type `text/event-stream` for the response with the status `200`
  - …2 more

[Change history](https://skmtc.dev/spiceai/apis/runtime/changes/v1/nsql/post.md)

---

[API](https://skmtc.dev/spiceai/apis/runtime.md) · [All operations](https://skmtc.dev/spiceai/apis/runtime/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/spiceai/runtime/revisions/fb597a4eaa56/schema)