Skip to main content
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.

​
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

Migration Guide

Step-by-step port from /nql/run, with a worked example

Executing NQL via the API

Full guide to /v1/nql/execute — parameters, tracking, and errors