> ## Documentation Index
> Fetch the complete documentation index at: https://docs.narrative.io/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /nql/run Deprecation

> POST /nql/run is deprecated. Use POST /v1/nql/execute instead.

**Surface:** `POST /nql/run` — deprecated, replaced by `POST /v1/nql/execute`

`/nql/run` continues to work. The removal timeline will be announced separately.

The steps below are the short version. For the full port — response shapes, patterns for each gap, and a worked example — see the [migration guide](/guides/nql/migrating-from-nql-run).

## What to do

1. Call `POST /v1/nql/execute` with the same request body. The `200` response contains the workflow `id` and the `run_id` of the run that just started.
2. Poll `GET /workflows/{workflow_id}/runs` until the run reports `completed` or `failed`.
3. For job-level detail, call `GET /jobs?workflow_run_id={run_id}` and read the `job_id` field.
4. For a dataset created by `CREATE MATERIALIZED VIEW`, look it up by name once the run completes, or read `result.dataset_id` from the completed job.

## What's different

* The response is a workflow and a run, not a job. The job id comes from step 3, and the field is `job_id` — `/nql/run` returned it as `id`.
* Datasets created by `CREATE MATERIALIZED VIEW` are resolved after the run instead of arriving in the response body.
* Success is `200` instead of `201`.
* Cancellation is `POST /workflows/{workflow_id}/runs/{run_id}/cancel`.
* Supported statements and error bodies are identical, apart from `instance`. Error handling needs no changes.

## Learn more

<CardGroup cols={2}>
  <Card title="Migration Guide" icon="arrow-right-arrow-left" href="/guides/nql/migrating-from-nql-run">
    Step-by-step port from /nql/run, with a worked example
  </Card>

  <Card title="Executing NQL via the API" icon="play" href="/guides/nql/executing-nql-via-api">
    Full guide to /v1/nql/execute — parameters, tracking, and errors
  </Card>
</CardGroup>