POST /nql/run is deprecated. Its replacement, POST /v1/nql/execute, takes the same request body and returns the same errors — but it hands back a workflow and a run instead of a job, so anything holding onto the job id has to change.
Deprecated does not mean removed.
/nql/run continues to work; the removal timeline will be announced separately.Why the change
NQL execution now runs on the same workflow engine as the rest of the platform, so an execution is a durable run you can track, schedule, and cancel like any other./v1/nql/execute is the single-statement case of that model, and the same task composes into larger multi-step workflows without changing transport. One execution model instead of two.
Make the call
The request does not change. Same body, same parameters — only the path:data_plane_id, compute_pool_id, and create_as_view are honored identically.
The response does change. Before, a 201 carrying a job — the job id in id, and the whole created dataset inline in input.dataset:
200 carrying the workflow and the run that just started. No job id, no dataset:
What to change
1
Accept 200 instead of 201
Success is now
200. A client asserting on 201 fails on every call.2
Read the workflow id, not a job id
id is the workflow id and run_id is the run id. Poll GET /workflows/{workflow_id}/runs for running, completed, or failed — for most callers that is the whole replacement for polling the job.3
Fetch the job only if you need failure detail
Call
GET /jobs?workflow_run_id={run_id}. The job is created seconds after the run starts, so poll until it appears.4
Resolve the created dataset after the run
input.dataset is gone, because the dataset does not exist yet when the response is sent. Once the run completes, look it up by the name you gave the view, or read result.dataset_id off the completed job. An optimistic “here is your new dataset” render now has nothing to draw until the run finishes.5
Delete execution_cluster if you still send it
Placement runs on compute pools now.
execution_cluster no longer decides where work runs and is not in the request schema for either endpoint — that code is dead.REFRESH_SCHEDULE still works (it becomes a workflow schedule), and error bodies are identical apart from instance — existing RFC 7807 handling needs no changes.
One addition rather than a change: runs are cancellable with POST /workflows/{workflow_id}/runs/{run_id}/cancel, where /nql/run only had request-cancellation.
Worked example
A complete sequence, trimmed to the interesting fields:Related content
Executing NQL via the API
Full guide to /v1/nql/execute — parameters, tracking, and errors
POST /nql/run Deprecation
The deprecation notice and its support window
Tracking Job Status
Polling patterns, backoff, and job result handling
Troubleshooting NQL
Reading RFC 7807 error responses