Executing NQL via the API

POST /v1/nql/execute runs one NQL statement as a workflow: send the statement, poll the run, read the result.

/v1/nql/execute replaces the deprecated POST /nql/run. If you have existing code calling /nql/run, see Migrating from /nql/run to /v1/nql/execute.

Prerequisites

A Narrative API token
Basic familiarity with NQL syntax

1. Run the statement

curl -X POST https://api.narrative.io/v1/nql/execute \
  -H "Authorization: Bearer $NIO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"nql": "CREATE MATERIALIZED VIEW \"active_users_by_region\" AS SELECT \"user_data\".\"region\", COUNT(1) AS \"user_count\" FROM \"user_data\" GROUP BY \"user_data\".\"region\""}'

The 200 response is the workflow that was created plus the id of the run that just started:

{
  "id": "93bba8c5-6db4-4c36-af3b-502e0bff268f",
  "name": "execute-nql-787b42e4-fe12-4a8e-a2f6-ed3d5e9b1b17",
  "run_id": "019ff635-5aee-7949-8e6a-8c47efa7fc56",
  "status": "active",
  "specification": "document:\n  dsl: 1.0.0\n  ..."
}

id is the workflow id; run_id is the run id. Keep both — every step below needs one of them. The endpoint runs one statement per request: CREATE MATERIALIZED VIEW, INSERT, UPDATE, DELETE, or EXPLAIN.

Request parameters

Parameter	Required	Description
`nql`	Yes	The NQL statement to run
`data_plane_id`	No	The data plane to run on
`compute_pool_id`	No	The compute pool that executes the statement
`create_as_view`	No	For `CREATE MATERIALIZED VIEW` only: register the result as a view dataset instead of materializing it. Ignored for other statements

A REFRESH_SCHEDULE on a CREATE MATERIALIZED VIEW statement becomes a workflow schedule, so scheduled refreshes run as workflow runs.

2. Track the run

Poll the workflow’s runs:

curl https://api.narrative.io/workflows/{workflow_id}/runs \
  -H "Authorization: Bearer $NIO_API_TOKEN"

{
  "runs": [
    {
      "run_id": "019ff635-5aee-7949-8e6a-8c47efa7fc56",
      "status": "running",
      "start_time": "2026-08-12T13:41:59Z",
      "close_time": null
    }
  ]
}

The run reports running, completed, or failed. If all you need is whether the statement succeeded, this is the whole story — stop here.

When you need failure detail

The statement executes as a job inside the run. To see state transitions, failures, or the result payload, list jobs by run id:

curl "https://api.narrative.io/jobs?workflow_run_id={run_id}" \
  -H "Authorization: Bearer $NIO_API_TOKEN"

{
  "records": [
    {
      "job_id": "5622058d-38c8-4eca-8c94-ba5c9c70a87f",
      "type": "materialize-view",
      "state": "pending",
      "workflow_id": "93bba8c5-6db4-4c36-af3b-502e0bff268f",
      "workflow_run_id": "019ff635-5aee-7949-8e6a-8c47efa7fc56"
    }
  ]
}

The job identifier field is job_id, not id. Code ported from /nql/run that reads id gets undefined rather than an error.

The job is created seconds after the run starts, so an immediate query can return an empty list — poll until it appears. The job carries workflow_id and workflow_run_id pointing back, so correlation works in both directions; workflow_id alone returns every job across all runs of that workflow. See Tracking Job Status for polling patterns and backoff.

3. Get the result

The dataset created by `CREATE MATERIALIZED VIEW`

The dataset does not exist when the response is sent — it is created when the run executes. Once the run reaches completed, get it either way:

Look it up by name. You named the view in the statement, so the name is already known to your code.

Read it off the completed job. The job result carries the dataset id:

{
  "state": "completed",
  "result": { "dataset_id": 42558, "snapshot_id": 6007775799525750167 }
}

Then fetch it with GET /datasets/42558.

The rows themselves

/v1/nql/execute does not return query results, and a bare SELECT is rejected with a 400. To read data back, materialize it with CREATE MATERIALIZED VIEW and then request a sample from the resulting dataset.

4. Cancel a run

Cancel an in-flight execution through the workflow run cancel endpoint:

curl -X POST https://api.narrative.io/workflows/{workflow_id}/runs/{run_id}/cancel \
  -H "Authorization: Bearer $NIO_API_TOKEN"

Errors

Errors are returned as RFC 7807 problem documents with title, status, detail, instance, log_id, and a debug object.

Status	When
`400`	The statement failed to compile, or is a statement type the endpoint cannot run — a bare `SELECT`, or a `MERGE` (`MERGE ON` deduplication is part of materialized view refresh behavior, not a standalone statement)
`422`	The statement parsed but is semantically invalid — for example, a materialized view output column with an unsupported type such as `DECIMAL`
`403`	The company has no usage credit for the target data plane, or the statement would create a view under a name that already exists

See Troubleshooting NQL for how to read these error bodies.

Migrating from /nql/run

Port existing callers of the deprecated endpoint

Workflow Orchestration

Chain multiple operations into one durable workflow

Tracking Job Status

Polling patterns, backoff, and job result handling

Materialized View Syntax

Complete reference for CREATE MATERIALIZED VIEW

Overview

Platform

Data Ingestion

Data Planes

Querying with NQL

Data Collaboration

Identity Resolution

Data Activation

Audience Studio

Connectors

Compliance

Rosetta Stone

Account Settings

Workflows

Webhooks

Data Collaboration MCP Server

Tools

SDKs

Prerequisites

1. Run the statement

Request parameters

2. Track the run

When you need failure detail

3. Get the result

The dataset created by `CREATE MATERIALIZED VIEW`

The rows themselves

4. Cancel a run

Errors

Migrating from /nql/run

Workflow Orchestration

Tracking Job Status

Materialized View Syntax

​Prerequisites

​1. Run the statement

​Request parameters

​2. Track the run

​When you need failure detail

​3. Get the result

​The dataset created by CREATE MATERIALIZED VIEW

​The rows themselves

​4. Cancel a run

​Errors

​Related content

Migrating from /nql/run

Workflow Orchestration

Tracking Job Status

Materialized View Syntax

Prerequisites

1. Run the statement

Request parameters

2. Track the run

When you need failure detail

3. Get the result

The dataset created by `CREATE MATERIALIZED VIEW`

The rows themselves

4. Cancel a run

Errors

Related content