Get Run Status

curl --request GET \
  --url https://api.usenexio.com/api/v1/runs/{run_id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.usenexio.com/api/v1/runs/{run_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usenexio.com/api/v1/runs/{run_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.usenexio.com/api/v1/runs/{run_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.usenexio.com/api/v1/runs/{run_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "run_id": "990d0fae-dc17-43af-aaed-ff8b580c17ab",
  "status": "queued",
  "environment": "test",
  "attempt": 1,
  "created_at": "2026-04-01T18:19:38.851Z"
}

GET

api

runs

{run_id}

Get Run Status

curl --request GET \
  --url https://api.usenexio.com/api/v1/runs/{run_id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.usenexio.com/api/v1/runs/{run_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usenexio.com/api/v1/runs/{run_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.usenexio.com/api/v1/runs/{run_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.usenexio.com/api/v1/runs/{run_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "run_id": "990d0fae-dc17-43af-aaed-ff8b580c17ab",
  "status": "queued",
  "environment": "test",
  "attempt": 1,
  "created_at": "2026-04-01T18:19:38.851Z"
}

Result phases

A placement run finishes all of its deterministic scoring before it calls the model, and it persists that answer at the boundary. From that moment the response carries a result while status is still processing. Two fields describe it:

Field	Type	Present when	Meaning
`completed_deterministic_at`	datetime	The run reached the deterministic boundary	RFC 3339 timestamp for when the run finished the deterministic part of its answer. Stamped mid-run, before the model leg, so it appears while `status` is still `processing`. Omitted on runs that have not reached the boundary, and on engines that have no such boundary.
`output_phase`	enum: `final`, `deterministic_draft`	The response carries `output` or `solutions`	Which answer those two fields carry. Omitted when the response carries neither, so neither is ever read without its phase.

Read output_phase for the distinction. Do not infer it from a status and timestamp combination.

`final`

The run’s terminal answer, complete. Served on completed and degraded runs, exactly as before this field existed.

`deterministic_draft`

The deterministic answer, served while status is still processing and the model leg runs. A draft is a real answer over part of the decision, not a preview. Its ranks, cluster labels, and overall_level values are real, but they are computed over the deterministic scoring dimensions only, with the weights renormalized over them. The model-scored dimensions are absent from a draft scorecard rather than empty or stubbed. Which dimensions are model-scored is set per engine by scoring_dimensions[*].method in the released engine configuration. Where the configuration also declares an assessed-weight floor, each scorecard carries assessed_weight_fraction: the share of the decision weight that scorecard covers. On a draft it reads well below 1, and on the final answer for the same solution it reads higher. The model-scored dimensions carry real weight, so the final answer can and does reorder the shortlist.

Never treat a draft as the final answer, and never stop polling on one. A draft is provisional until the same run_id returns output_phase: final.

A failed or cancelled run carries no output and no solutions, and therefore no output_phase, even when it reached the boundary before it failed. A draft is never served on a failed run. Only the placement engine has a deterministic boundary today. Runs on engines that have none omit both fields until they reach a terminal status.

Rendering a result before the run finishes

Keep the polling loop exactly as it is: it exits on completed, degraded, or failed. To show a result sooner, render the draft from inside the loop and replace it when the final answer arrives.

# One poll. Branch on output_phase, not on status alone.
curl -s https://api.usenexio.com/api/v1/runs/$RUN_ID \
  -H "Authorization: Bearer $NEXIO_API_KEY" \
  | jq '{status, output_phase, completed_deterministic_at,
         top: .solutions[0] | {rank, cluster_label,
                               overall_level: .scorecard.overall_level,
                               assessed: .scorecard.assessed_weight_fraction}}'

import time

import httpx

TERMINAL = ("completed", "degraded", "failed", "cancelled")


def poll_run(api_key: str, run_id: str, on_draft=None) -> dict:
    """Poll to terminal. Call on_draft with each deterministic draft seen."""
    headers = {"Authorization": f"Bearer {api_key}"}
    delay = 2.0
    drafted = False
    while True:
        run = httpx.get(
            f"https://api.usenexio.com/api/v1/runs/{run_id}",
            headers=headers,
        ).json()

        if run["status"] in TERMINAL:
            # output_phase is "final" here, or absent on a failed run.
            return run

        if on_draft and not drafted and run.get("output_phase") == "deterministic_draft":
            # A real answer over the deterministic dimensions. Render it as
            # provisional, then keep polling: the final answer can reorder it.
            on_draft(run)
            drafted = True

        time.sleep(delay)
        delay = min(delay * 1.5, 30.0)

const TERMINAL = ['completed', 'degraded', 'failed', 'cancelled']

type RunResponse = {
  status: string
  output_phase?: 'final' | 'deterministic_draft'
  completed_deterministic_at?: string
  output?: Record<string, unknown>
  solutions?: Array<Record<string, unknown>>
}

export async function pollRun(
  apiKey: string,
  runId: string,
  onDraft?: (run: RunResponse) => void,
): Promise<RunResponse> {
  const headers = { Authorization: `Bearer ${apiKey}` }
  let delay = 2000
  let drafted = false

  for (;;) {
    const res = await fetch(`https://api.usenexio.com/api/v1/runs/${runId}`, { headers })
    const run: RunResponse = await res.json()

    // output_phase is "final" here, or absent on a failed run.
    if (TERMINAL.includes(run.status)) return run

    if (onDraft && !drafted && run.output_phase === 'deterministic_draft') {
      // A real answer over the deterministic dimensions. Render it as
      // provisional, then keep polling: the final answer can reorder it.
      onDraft(run)
      drafted = true
    }

    await new Promise((resolve) => setTimeout(resolve, delay))
    delay = Math.min(delay * 1.5, 30000)
  }
}

Two rules keep this correct:

The loop exits on status, never on output_phase. A draft is not an exit condition.
Anything you render from a draft is labeled provisional in your interface and is replaced by the final response for the same run_id.

Reading the stored output block

The run’s output object carries its own output_phase key, with the same two values as the envelope field. A consumer that reads the output block on its own, rather than the whole response, can still tell a draft from a final answer without the envelope. This applies to placement-engine output blocks.

Webhooks carry no phase

Webhook payloads do not carry output_phase or completed_deterministic_at. Every webhook event type is terminal, so a delivered run has already passed the boundary and its phase would be the constant final. There is no webhook event for the deterministic boundary. Polling is the only surface that serves a draft.

Authorizations

Authorization

string

header

required

Send the credential as Authorization: Bearer <key>.

Scoped partner credentials use the exclusive nxsk_v1_... namespace. Each scoped key is bound at issuance to one organization, one canonical named environment, an explicit engine set, and a least-privilege capability set. A malformed, unknown, rotated, or revoked nxsk_ key fails closed and is never retried as a legacy key.

Capabilities used by this API are runs:write, runs:read, engines:read, catalog:read, webhooks:manage, runs:defensibility:read, runs:test, conversations:use, and conversations:export. Operation descriptions name the required capability. Grandfathered nx_live_... and nx_test_... keys retain their existing broad access during the compatibility window.

Path Parameters

run_id

string<uuid>

required

The run identifier returned by POST /api/v1/engines/{engine_slug}/runs.

Response

Current run status and results (if completed).

run_id

string<uuid>

required

Stable run identifier.

status

enum<string>

required

Current run status. queued and processing are non-terminal: keep polling. completed, degraded, failed, and cancelled are terminal. degraded carries the same output shape as completed plus output.degradation_reason: treat it as a successful response with a warning, not as a state to keep polling on.

Available options:

queued,

processing,

completed,

degraded,

failed,

cancelled

environment

enum<string>

required

Environment the run executed in.

Available options:

test,

live

attempt

integer

required

Execution attempt count. A terminal value of 1 means no worker retry.

Required range: x >= 0

created_at

string<date-time>

required

RFC 3339 timestamp when the run was created.

engine_type

string

Runtime engine type. Omitted on legacy rows without engine metadata.

engine_version

string

The released engine version this run executed against (major.minor), resolved from the engine_version pin at submit time and frozen for the run's lifetime. Absent when the run used the engine's current configuration without a pin.

Example:

"1.3"

engine_config_version_hash

string

Immutable hash of the archived engine configuration this run executed. Resolved and frozen at submission alongside engine_version. Absent on legacy unstamped runs.

Example:

"297c960d80b848c9"

stage

string

Last known pipeline stage (e.g. EVALUATE, FILTER).

output

object

Run summary. Present on terminal runs, and on a processing placement run that reached the deterministic boundary. Read the top-level output_phase to know which answer it is.

Show child attributes

duration_ms

integer

Duration of the final execution attempt in milliseconds.

total_duration_ms

integer

Wall-clock milliseconds from creation to terminal completion.

error

string

Error message on failed runs.

error_details

object

Structured failure details.

trace_id

string

Trace identifier for support correlation.

Pattern: ^[0-9a-f]{32}$

completed_at

string<date-time>

RFC 3339 timestamp when the run reached a terminal state.

completed_deterministic_at

string<date-time>

RFC 3339 timestamp when the run finished the deterministic part of its answer. It is stamped mid-run, before the model leg, so it is present while status is still processing, and it is what makes a draft servable ahead of completion. Omitted on runs that have not reached that boundary, and on engines that have no such boundary (only the placement engine has one today). Never present on webhook payloads: every webhook event is terminal and has passed the boundary already.

output_phase

enum<string>

Which answer output and solutions carry. Present whenever the response carries either of them, and omitted when it carries neither, so neither is ever read without its phase. Read this field for the distinction: do not infer it from a status and timestamp combination.

final is the run's terminal answer, complete. It is served on completed and degraded runs.

deterministic_draft is the deterministic answer, served while status is still processing. Its ranks, cluster labels, and overall_level values are real, but they are computed over the deterministic scoring dimensions only, with the weights renormalized over them. The model-scored dimensions are absent from a draft scorecard rather than empty, and they carry real weight, so the final answer can reorder the shortlist. Render a draft as provisional and keep polling.

A failed run carries neither field, and therefore no phase, even when it reached the boundary before it failed. Never present on webhook payloads: every webhook event is terminal, so the phase there would be the constant final.

Available options:

final,

deterministic_draft

solutions

object[]

Ranked solutions. Present on terminal placement runs, and on a processing placement run that reached the deterministic boundary. Read output_phase to know which answer they are.

Show child attributes

warnings

object

Structured input-quality warnings. Present only when the released engine configuration enables warning exposure.

object
object[]

Start Here

Guides

API Reference

Get Run Status

Result phases

`final`

`deterministic_draft`

Rendering a result before the run finishes

Reading the stored output block

Webhooks carry no phase

Authorizations

Path Parameters

Response

​Result phases

​final

​deterministic_draft

​Rendering a result before the run finishes

​Reading the stored output block

​Webhooks carry no phase

Authorizations

Path Parameters

Response

Result phases

`final`

`deterministic_draft`

Rendering a result before the run finishes

Reading the stored output block

Webhooks carry no phase