Skip to main content
POST
Cancel Run

Behavior

A queued run becomes cancelled at once. A processing run stops at its next cancellation check, so poll until it is terminal. A run that is already terminal is returned unchanged with 200. See Runs.

Authorizations

Authorization
string
header
required

Send the key as Authorization: Bearer <key>. Two kinds of key exist.

Organization keys are issued in the portal (Settings, then API keys), each bound to one environment, shaped nx_<environment slug>_<64 hex>. They carry no capabilities and pass every capability check, with one exception: routes under /api/v1/records, /api/v1/engines/{id}/opportunities, /api/v1/graph and /api/v1/catalog/documents accept an organization key only when its environment is live, and refuse any other with 403 scoped_key_required. Revocation takes effect within 60 seconds.

Scoped keys are issued by Nexio on request, shaped nxsk_v1_<24 hex key id>_<43 character secret>. Each is bound to one org, one environment, a set of engines and a set of capabilities. A malformed, unknown or revoked nxsk_ key fails with 401 and is never retried as an organization key. Revocation takes effect on the next request. A scoped key without a route's capability gets 403 insufficient_capability; a scoped key not bound to the engine gets 403 engine_binding_forbidden.

Key-grantable capabilities: engines:read, runs:write, runs:read, runs:defensibility:read, runs:test, catalog:read, catalog:documents:read, webhooks:manage, conversations:use, conversations:export, records:read, records:opportunities:run, actions:write, actions:read, graph:read, records:analyze.

Routes that accept organization keys only (every scoped key gets 403 insufficient_capability): environment management, engine create, update, configuration and publish, and conversation instance authoring. Each operation description names the capability a scoped key needs.

Path Parameters

run_id
string<uuid>
required

Body

application/json
reason
string

Free text stored with the first cancel request, trimmed. The whole body is limited to 16 KiB.

Response

The run was already terminal and is unchanged. The body is the run's status fields and stored output, built without solutions: it carries no solutions, input, work_items, warnings, computed_at_head, served_head or stale. output is the stored output as written: a matching run's operator block is not trimmed and no acting principal's field policy is applied. Read the served result with GET /api/v1/runs/{run_id}.

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 output; read output.degradation_reason (entity analysis) or output.partial (matching). See Runs.

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: comparison, matching, entity_analysis, diligence, triage or opportunity. Runs recorded before the cutover keep placement. Omitted on legacy rows without engine metadata.

engine_version
string

The engine version this run executed against, resolved at submit time and frozen for the run's lifetime. A released major.minor label when the run was pinned to a release (N.M or N.x) or sent no pin (an unpinned public submission resolves to the latest release). The literal draft when a sandbox key pinned draft and the run executed the unpublished configuration. Absent only on older or internal records that carry no version stamp.

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"

parked_until
string<date-time>

Scheduled resume from the latest warehouse wait. Present while processing until a worker heartbeat confirms resume. Keep polling past this deadline.

park_reason
string

Reason for the active park. Present alongside parked_until.

last_parked_until
string<date-time>

Latest warehouse wait deadline, retained after resume so clients can extend their polling budget through the park.

stage
string

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

output
object

Run output. Present only on completed and degraded runs. The shape comes from the engine's declared response schema, which its type derives from its configuration; see Engine types. The named properties below are written by specific types.

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>

When a run of the comparison type finished its deterministic scoring. Stamped mid-run, so it can appear while status is still processing. A timing fact only: no output is served until the run is completed or degraded. Absent on other engine types and on webhook payloads.

output_phase
enum<string>

Which answer output and solutions carry. Present on every completed and degraded run, and then always final, even when solutions (for example on an engine that produces none) or output is absent. Absent on queued, processing, failed and cancelled runs, and on webhook payloads.

Available options:
final,
deterministic_draft
solutions
object[]

Ranked results. Present on completed and degraded runs of the types that rank them (comparison, matching), when at least one was produced.

warnings
object

Structured input-quality warnings. Present only when the run recorded warnings and the engine's current saved configuration sets expose_warnings: true when the run is read. The setting is read on each request, not from the release the run used.

started_at
string<date-time>

When a worker first started the run.

input
object

The admitted submission. Present only with include=input.

computed_at_head
string

The source data head the run computed against, on runs of engines Nexio operates that are recorded as a result in a connected system of record.

served_head
string

The source data head served now, on the same runs.

stale
boolean

True when the assessed subject changed between the head the run computed against (computed_at_head) and the head that now serves it (served_head). A result carried to a newer head unchanged has stale: false. Present on the same runs as computed_at_head.

work_items
object

Compact rollup of the run's work items: total, required, required_complete, required_incomplete, required_failed, required_cancelled, optional problems, and suggested_terminal.

Last modified on September 25, 2026