curl --request POST \
--url https://api.usenexio.com/api/v1/runs/{run_id}/cancel \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"reason": "<string>"
}
'import requests
url = "https://api.usenexio.com/api/v1/runs/{run_id}/cancel"
payload = { "reason": "<string>" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({reason: '<string>'})
};
fetch('https://api.usenexio.com/api/v1/runs/{run_id}/cancel', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "queued",
"environment": "test",
"attempt": 1,
"created_at": "2023-11-07T05:31:56Z",
"engine_type": "<string>",
"engine_version": "1.3",
"engine_config_version_hash": "297c960d80b848c9",
"parked_until": "2023-11-07T05:31:56Z",
"park_reason": "<string>",
"last_parked_until": "2023-11-07T05:31:56Z",
"stage": "<string>",
"output": {
"output_phase": "final",
"enrichment": {},
"diagnostic": "<string>",
"degradation_reason": "no_requirements",
"requirement_count": 123,
"solutions_count": 123,
"appetite_bucket": "<string>",
"top_label": "<string>",
"top_score": 123
},
"duration_ms": 123,
"total_duration_ms": 123,
"error": "<string>",
"error_details": {},
"trace_id": "<string>",
"completed_at": "2023-11-07T05:31:56Z",
"completed_deterministic_at": "2023-11-07T05:31:56Z",
"output_phase": "final",
"solutions": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"offerings": [
{
"id": "<string>",
"provider_name": "<string>",
"category": "<string>",
"data_currency": {
"effective_year": 123,
"effective_date": "2023-12-25",
"stale": true,
"undated": true,
"effective_date_basis": "stated"
},
"alternates": [
{
"offering_id": "<string>",
"provider_name": "<string>",
"scorecard": {}
}
]
}
],
"requirements_met": [
"<string>"
],
"provider_count": 123,
"scorecard": {
"overall_level": 123,
"coverage_completeness": {
"level": 2,
"label": "<string>",
"justification": "<string>",
"method": "deterministic"
},
"pricing_competitiveness": {
"level": 2,
"label": "<string>",
"justification": "<string>",
"method": "deterministic"
},
"provider_quality": {
"level": 2,
"label": "<string>",
"justification": "<string>",
"method": "deterministic"
},
"placement_likelihood": {
"level": 2,
"label": "<string>",
"justification": "<string>",
"method": "deterministic"
},
"operational_simplicity": {
"level": 2,
"label": "<string>",
"justification": "<string>",
"method": "deterministic"
},
"risk_alignment": {
"level": 2,
"label": "<string>",
"justification": "<string>",
"method": "deterministic"
},
"assessed_weight_fraction": 0.5,
"run_position": {
"percentile": 123,
"tied": 123,
"population": 123,
"population_unit": "<string>",
"basis": "<string>",
"field_best": 123,
"field_worst": 123,
"margin": 123
}
},
"est_cost_low": 123,
"est_cost_high": 123,
"consolidation_discount": 123,
"bundle": {
"offering_ids": [
"<string>"
],
"joined_premium_annual": 1,
"standalone_premium_annual": 1,
"savings_annual": 1
},
"cluster_label": "<string>",
"rank": 123,
"headline": "<string>",
"narrative": "<unknown>"
}
],
"warnings": {},
"started_at": "2023-11-07T05:31:56Z",
"input": {},
"computed_at_head": "<string>",
"served_head": "<string>",
"stale": true,
"work_items": {}
}{
"run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "<string>",
"cancel_requested_at": "2023-11-07T05:31:56Z"
}{
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}{
"code": "unauthorized",
"message": "Missing or invalid API key"
}{
"code": "engine_binding_forbidden",
"message": "API key is not bound to this run's engine"
}{
"code": "run_not_found",
"message": "Run not found"
}{
"code": "rate_limited",
"message": "Rate limit exceeded"
}{
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}{
"code": "auth_unavailable",
"message": "API key authentication is temporarily unavailable"
}{
"code": "request_timeout",
"message": "Request timed out"
}Cancel run
Ask Nexio to stop a queued or processing run.
curl --request POST \
--url https://api.usenexio.com/api/v1/runs/{run_id}/cancel \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"reason": "<string>"
}
'import requests
url = "https://api.usenexio.com/api/v1/runs/{run_id}/cancel"
payload = { "reason": "<string>" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({reason: '<string>'})
};
fetch('https://api.usenexio.com/api/v1/runs/{run_id}/cancel', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "queued",
"environment": "test",
"attempt": 1,
"created_at": "2023-11-07T05:31:56Z",
"engine_type": "<string>",
"engine_version": "1.3",
"engine_config_version_hash": "297c960d80b848c9",
"parked_until": "2023-11-07T05:31:56Z",
"park_reason": "<string>",
"last_parked_until": "2023-11-07T05:31:56Z",
"stage": "<string>",
"output": {
"output_phase": "final",
"enrichment": {},
"diagnostic": "<string>",
"degradation_reason": "no_requirements",
"requirement_count": 123,
"solutions_count": 123,
"appetite_bucket": "<string>",
"top_label": "<string>",
"top_score": 123
},
"duration_ms": 123,
"total_duration_ms": 123,
"error": "<string>",
"error_details": {},
"trace_id": "<string>",
"completed_at": "2023-11-07T05:31:56Z",
"completed_deterministic_at": "2023-11-07T05:31:56Z",
"output_phase": "final",
"solutions": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"offerings": [
{
"id": "<string>",
"provider_name": "<string>",
"category": "<string>",
"data_currency": {
"effective_year": 123,
"effective_date": "2023-12-25",
"stale": true,
"undated": true,
"effective_date_basis": "stated"
},
"alternates": [
{
"offering_id": "<string>",
"provider_name": "<string>",
"scorecard": {}
}
]
}
],
"requirements_met": [
"<string>"
],
"provider_count": 123,
"scorecard": {
"overall_level": 123,
"coverage_completeness": {
"level": 2,
"label": "<string>",
"justification": "<string>",
"method": "deterministic"
},
"pricing_competitiveness": {
"level": 2,
"label": "<string>",
"justification": "<string>",
"method": "deterministic"
},
"provider_quality": {
"level": 2,
"label": "<string>",
"justification": "<string>",
"method": "deterministic"
},
"placement_likelihood": {
"level": 2,
"label": "<string>",
"justification": "<string>",
"method": "deterministic"
},
"operational_simplicity": {
"level": 2,
"label": "<string>",
"justification": "<string>",
"method": "deterministic"
},
"risk_alignment": {
"level": 2,
"label": "<string>",
"justification": "<string>",
"method": "deterministic"
},
"assessed_weight_fraction": 0.5,
"run_position": {
"percentile": 123,
"tied": 123,
"population": 123,
"population_unit": "<string>",
"basis": "<string>",
"field_best": 123,
"field_worst": 123,
"margin": 123
}
},
"est_cost_low": 123,
"est_cost_high": 123,
"consolidation_discount": 123,
"bundle": {
"offering_ids": [
"<string>"
],
"joined_premium_annual": 1,
"standalone_premium_annual": 1,
"savings_annual": 1
},
"cluster_label": "<string>",
"rank": 123,
"headline": "<string>",
"narrative": "<unknown>"
}
],
"warnings": {},
"started_at": "2023-11-07T05:31:56Z",
"input": {},
"computed_at_head": "<string>",
"served_head": "<string>",
"stale": true,
"work_items": {}
}{
"run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "<string>",
"cancel_requested_at": "2023-11-07T05:31:56Z"
}{
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}{
"code": "unauthorized",
"message": "Missing or invalid API key"
}{
"code": "engine_binding_forbidden",
"message": "API key is not bound to this run's engine"
}{
"code": "run_not_found",
"message": "Run not found"
}{
"code": "rate_limited",
"message": "Rate limit exceeded"
}{
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}{
"code": "auth_unavailable",
"message": "API key authentication is temporarily unavailable"
}{
"code": "request_timeout",
"message": "Request timed out"
}Behavior
A queued run becomescancelled 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
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
Body
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}.
Stable run identifier.
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.
queued, processing, completed, degraded, failed, cancelled Environment the run executed in.
test, live Execution attempt count. A terminal value of 1 means no worker retry.
x >= 0RFC 3339 timestamp when the run was created.
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.
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.
"1.3"
Immutable hash of the archived engine configuration this run
executed. Resolved and frozen at submission alongside
engine_version. Absent on legacy unstamped runs.
"297c960d80b848c9"
Scheduled resume from the latest warehouse wait. Present while processing until a worker heartbeat confirms resume. Keep polling past this deadline.
Reason for the active park. Present alongside parked_until.
Latest warehouse wait deadline, retained after resume so clients can extend their polling budget through the park.
Last known pipeline stage (e.g. EVALUATE, FILTER).
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.
Hide child attributes
Hide child attributes
The stored block's own copy of the top-level output_phase. Always
final on a served output. Written on comparison output blocks.
final, deterministic_draft Per-source enrichment outcome blocks keyed by handler kind.
Hide child attributes
Hide child attributes
Terminal outcome for one configured and enabled enrichment source.
status and attempted are present on every run completed under the
current outcome contract; enrichment blocks retrieved from runs
archived before that rollout omit them, so treat both as optional. payload is required for succeeded and
not_mapped and absent for all other statuses. fetched_at is
optional. Block diagnostics are byte-equivalent to the matching entries
in the top-level output diagnostics array.
not_mapped means the source returned no mapped feature. It does not
mean no flood risk. Public-source data and cache entries may be stale.
FEMA degraded and circuit-open diagnostics use bounded
details.upstream values google_geocoding and nfhl.
Hide child attributes
Hide child attributes
"fema_nfhl"
succeeded, not_mapped, skipped, ambiguous, unavailable False when no upstream attempt occurred, including a cache hit or pre-call skip.
Required for succeeded and not_mapped; absent otherwise. A
successful fema_nfhl payload always includes sfha; it is a
boolean when FEMA supplied T/F and explicit JSON null when unknown.
comparison type: why nothing was ranked.
Stable reason on degraded runs, and on comparison runs that completed
with nothing ranked. Customer automation routes on this instead of
parsing free-text from diagnostic. When multiple non-info diagnostics
are present, strict precedence picks the most actionable single reason:
input_quality > llm_degraded >
enrichment_degraded > other. mixed and scoring_rule_failed
are defined but not emitted. insufficient_corpus is set on
completed runs by a decline gate that runs only when a platform
setting enables it. Outputs of matching runs report loss in
output.partial instead.
no_requirements, no_offerings, no_combinations, input_quality, llm_degraded, enrichment_degraded, scoring_rule_failed, mixed, other, insufficient_corpus comparison type: number of required categories evaluated.
comparison type: number of ranked results generated.
comparison type: the weight profile the run ranked with (coverage_first, cost_sensitive, balanced, simplicity).
comparison type: label of the top-ranked result (e.g. recommended, best_value).
comparison type: overall score of the top-ranked result.
Duration of the final execution attempt in milliseconds.
Wall-clock milliseconds from creation to terminal completion.
Error message on failed runs.
Structured failure details.
Trace identifier for support correlation.
^[0-9a-f]{32}$RFC 3339 timestamp when the run reached a terminal state.
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.
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.
final, deterministic_draft Ranked results. Present on completed and degraded runs of the
types that rank them (comparison, matching), when at least one was
produced.
Hide child attributes
Hide child attributes
Stable solution identifier within this run.
Offerings included in this solution package.
Hide child attributes
Hide child attributes
Line-level offering identifier (matches an entry in the submitted offerings).
Provider display name.
Requirement category (domain-specific, e.g. home, auto, umbrella).
Freshness of this offering's underlying source data. Serialized on
each offering object within a ranked solution (the engine's
Offering); clients read it at solutions[].offerings[].data_currency.
Present only for offerings loaded from a materialized connection.
Hide child attributes
Hide child attributes
The source schedule's effective business year, when known.
The product's effective date (YYYY-MM-DD), when known.
True when the source data is older than the freshness window (more than one year old) or undated. Show a stale offering with a caution that its rates can be out of date.
True when no effective year or date is known at all.
Where effective_date came from, so a synthesized day is never read
as a stated one. stated means the source document reported a
per-line date and it is the date shown. schedule_year means the
document stated only a year, so the date is January 1 of that year:
read the year, do not read the day. absent means no date is
available at all. Present only on engines that emit seat facts;
omitted otherwise.
stated, schedule_year, absent Other offerings that would have filled THIS seat: offerings whose
answer on every per-seat axis matches the seated one exactly, so
the engine ranks one and carries the rest here instead
of as near-identical ranked entries. Every alternate cleared the
same eligibility this line's seated offering did, and each carries
its own per-seat scorecard. Read at
solutions[].offerings[].alternates. Present only on engine versions
that emit alternates; omitted otherwise. Runs of the matching type
do not populate it: they list other candidates by ID at
offerings[].attributes.matching.alternates.
Hide child attributes
Hide child attributes
Line-level offering identifier, from this run's own candidates.
Provider display name.
This alternate seat's own answer on the per-provider axes:
market_entity_key, line, and one dimension per axis.
Requirement markers satisfied, as lob_<category> (for example lob_home).
Number of distinct providers in this solution.
Evaluation scorecard. overall_level is always present. Dimension
keys are configured per released engine version; the named properties
below are the default dimensions of the comparison type, not an
exhaustive set.
A dimension the run had no signal to score is present with level
0 and method suppressed, and overall_level is the weighted
level over the scored dimensions only. For a scored solution,
overall_level is on a 1 to 4 scale where higher is better (a level 1
dimension counts as 4). A solution from a matching run is not scored
this way: its scorecard carries overall_level: 0 and no dimensions or
fit_score.
Hide child attributes
Hide child attributes
Raw weighted level across configured dimensions. Use the
solution's emitted rank, not this value, as the ordering contract.
Hide child attributes
Hide child attributes
Rating from 1 (best) to 4 (worst). 0 means the dimension was not scored (method is suppressed).
0 <= x <= 4Human-readable label for this level.
Reasoning for the assigned level.
How this dimension was scored. suppressed means there was no signal to score it and it is left out of overall_level.
deterministic, llm, fallback, suppressed Hide child attributes
Hide child attributes
Rating from 1 (best) to 4 (worst). 0 means the dimension was not scored (method is suppressed).
0 <= x <= 4Human-readable label for this level.
Reasoning for the assigned level.
How this dimension was scored. suppressed means there was no signal to score it and it is left out of overall_level.
deterministic, llm, fallback, suppressed Hide child attributes
Hide child attributes
Rating from 1 (best) to 4 (worst). 0 means the dimension was not scored (method is suppressed).
0 <= x <= 4Human-readable label for this level.
Reasoning for the assigned level.
How this dimension was scored. suppressed means there was no signal to score it and it is left out of overall_level.
deterministic, llm, fallback, suppressed Hide child attributes
Hide child attributes
Rating from 1 (best) to 4 (worst). 0 means the dimension was not scored (method is suppressed).
0 <= x <= 4Human-readable label for this level.
Reasoning for the assigned level.
How this dimension was scored. suppressed means there was no signal to score it and it is left out of overall_level.
deterministic, llm, fallback, suppressed Hide child attributes
Hide child attributes
Rating from 1 (best) to 4 (worst). 0 means the dimension was not scored (method is suppressed).
0 <= x <= 4Human-readable label for this level.
Reasoning for the assigned level.
How this dimension was scored. suppressed means there was no signal to score it and it is left out of overall_level.
deterministic, llm, fallback, suppressed Hide child attributes
Hide child attributes
Rating from 1 (best) to 4 (worst). 0 means the dimension was not scored (method is suppressed).
0 <= x <= 4Human-readable label for this level.
Reasoning for the assigned level.
How this dimension was scored. suppressed means there was no signal to score it and it is left out of overall_level.
deterministic, llm, fallback, suppressed Share of the enabled scoring weight this scorecard actually scored. Emitted only by engine versions that declare an assessed-weight floor.
0 <= x <= 1Where this solution sits inside its own run's field. Emitted only by engine versions that enable it. An absolute band does not discriminate on a narrow field, so position is measured against the run's own spread.
The population is the solutions this run assembled, scored and ranked,
excluding any that fell below the engine's assessed-weight floor: those
did not compete, and they carry no run_position at all.
Hide child attributes
Hide child attributes
Midrank percentile of overall_level over the population, higher
being better, with ties corrected. Every member of a fully tied
field reads 50.
How many solutions share this exact basis value, including this
one. Counted in population_unit. 1 means unique.
How many solutions the percentile was measured over, counted in population_unit.
What population and tied count.
What percentile, margin, field_best and field_worst measure.
The population's best value on basis.
The population's worst value on basis. With field_best it gives
the field's own spread, which is what turns a margin into a
judgment without holding the whole field.
Gap in basis to the next solution down in the population. Absent
on the lowest solution, which has no next. 0 is a real value and
means an exact tie.
Estimated annual cost, low end.
Estimated annual cost, high end.
Bundling discount applied to this solution, as a fraction
(0.0 to 1.0). Derived from
bundle.standalone_premium_annual and
bundle.joined_premium_annual when a bundle is applied; 0
otherwise.
Present on a Solution when a provider-supplied bundle was applied. Lists the offerings that bundle together, the provider's joined annual price, the sum of standalone annual prices, and the dollar-per-year savings. Omitted on standalone solutions.
Hide child attributes
Hide child attributes
IDs of every offering that participates in the applied bundle.
x >= 0x >= 0standalone_premium_annual minus joined_premium_annual,
clamped to zero when the provider's bundled price meets or
exceeds the standalone sum.
x >= 0Solution label indicating where it excels: recommended,
best_value, best_coverage, simplest.
Rank position (1 = best).
A one-line summary of the solution. Omitted when the run produced none.
A structured explanation of the solution, as JSON. Omitted when the run produced none.
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.
- object
- object[]
When a worker first started the run.
The admitted submission. Present only with include=input.
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.
The source data head served now, on the same runs.
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.
Compact rollup of the run's work items: total, required,
required_complete, required_incomplete, required_failed,
required_cancelled, optional problems, and
suggested_terminal.