> ## Documentation Index > Fetch the complete documentation index at: https://docs.usenexio.com/llms.txt > Use this file to discover all available pages before exploring further. # Get Run Status > Poll the status, solution, and metadata for a previously submitted run. ## OpenAPI ````yaml GET /api/v1/runs/{run_id} openapi: 3.1.0 info: title: Nexio API version: '1.0' description: | Nexio agentic infrastructure API. Configure engines for placement, entity analysis, and other patterns. Submit runs, poll for results, or subscribe to signed webhook callbacks. contact: email: support@usenexio.com url: https://docs.usenexio.com servers: - url: https://api.usenexio.com description: Production security: - BearerAuth: [] tags: - name: EngineManagement description: Create, configure, and manage inference engines. - name: Engines description: Engine-scoped endpoints for submitting runs and retrieving results. - name: Runs description: Retrieve and reconcile submitted runs. - name: Catalog description: >- Read current carriers and products extracted for the authenticated organization. - name: Environments description: Isolated tenancy scopes under your org (one live plus non-live sandboxes). - name: Webhooks description: Manage webhook endpoints for push-based delivery of terminal run events. paths: /api/v1/runs/{run_id}: get: tags: - Runs summary: Get Run Status description: > Retrieve processing state and ranked results for a submitted run. Poll until `status` reaches a terminal state (`completed`, `degraded`, or `failed`). `degraded` is terminal and carries the same shape as `completed` plus `output.degradation_reason` describing the cause: treat it as a successful response with a warning, not as a state to keep polling on. Run IDs are globally unique: no engine slug needed. Scoped partner keys require `runs:read`. The key's engine binding and canonical named environment must both match the run. A run outside that scope returns the same `404` as a missing run. This endpoint remains the canonical recovery and reconciliation read even if you also subscribe to webhooks. ### Polling guidance Use exponential backoff instead of tight loops. Start at 2 seconds, multiply by 1.5, cap at 30 seconds. ### Status values | Status | Meaning | |--------|---------| | `queued` | Run received, waiting for worker | | `processing` | Pipeline actively running | | `completed` | Results available in `solutions` | | `degraded` | Terminal output is available with warnings or partial results | | `failed` | Run ended with an error | operationId: getRunStatus parameters: - name: run_id in: path required: true description: >- The run identifier returned by `POST /api/v1/engines/{engine_slug}/runs`. schema: type: string format: uuid responses: '200': description: Current run status and results (if completed). content: application/json: schema: $ref: '#/components/schemas/RunStatusResponse' examples: queued: summary: Queued value: run_id: 990d0fae-dc17-43af-aaed-ff8b580c17ab status: queued environment: test attempt: 1 created_at: '2026-04-01T18:19:38.851Z' processing: summary: Processing value: run_id: 990d0fae-dc17-43af-aaed-ff8b580c17ab status: processing environment: test stage: EVALUATE attempt: 1 created_at: '2026-04-01T18:19:38.851Z' completed: summary: Completed value: run_id: 990d0fae-dc17-43af-aaed-ff8b580c17ab status: completed environment: test stage: COMPLETED attempt: 1 output: diagnostic: null requirement_count: 3 solutions_count: 7 appetite_bucket: balanced top_label: recommended top_score: 3.85 duration_ms: 18523 solutions: - id: 0b058b72-dec6-4ef9-915f-546fa6cb9377 rank: 1 cluster_label: recommended requirements_met: - lob_auto - lob_home - lob_umbrella provider_count: 1 est_cost_low: 11985 est_cost_high: 11985 consolidation_discount: 0.12 offerings: - id: quote_line_carrier_c_auto_001 provider_name: Carrier C category: auto - id: quote_line_carrier_c_home_001 provider_name: Carrier C category: home - id: quote_line_carrier_c_umbrella_001 provider_name: Carrier C category: umbrella scorecard: overall_level: 3.85 created_at: '2026-04-01T18:19:38.851Z' completed_at: '2026-04-01T18:19:57.401Z' completed_no_combinations: summary: Completed with no candidates (degraded) description: > A placement run that completed cleanly but produced no usable output. Indicated by `output.degradation_reason`. Customers routing on `output.solutions_count == 0` should also surface `degradation_reason` so brokers see why no candidates came back. `output.degradation_reason` is a stable string enum that customer automation can switch on instead of parsing free-text from `output.diagnostic` or walking `warning_details[]`. Defined values: - `no_requirements` : no coverage requirements parsed from input - `no_offerings` : every offering filtered out before scoring - `no_combinations` : no candidate placement combinations - `input_quality` : customer-fixable input warning (MALFORMED_FIELD, MISSING_FIELD, OUT_OF_RANGE, FIELD_CONFLICT) - `llm_degraded` : LLM provider failure - `enrichment_degraded`: enrichment upstream outage - `scoring_rule_failed`: engine-side scoring rule violation - `mixed` : reserved for future use; not currently emitted. Defined so customer-side switches don't break if precedence is loosened later - `other` : non-info diagnostic that doesn't match a known family (catchall for new producers) When multiple non-info diagnostics are present, strict precedence picks the most actionable single reason: `scoring_rule_failed` > `input_quality` > `llm_degraded` > `enrichment_degraded` > `other`. Adding a new value requires a spec; existing values are stable. value: run_id: 5fb2b5f9-04a3-4cd5-94f2-29a72ba9b317 status: completed environment: test stage: COMPLETED attempt: 1 output: diagnostic: No valid placement combinations found degradation_reason: no_combinations requirement_count: 3 solutions_count: 0 appetite_bucket: balanced top_label: null top_score: null duration_ms: 14210 solutions: [] created_at: '2026-04-01T19:05:11.221Z' completed_at: '2026-04-01T19:05:25.431Z' completed_gap_analysis: summary: Entity-analysis run with broker-readable evidence labels description: | A gap-analysis run on an engine configured with `data_source_labels`. Each gap's `data_source_labels[]` is index-aligned with `data_sources[]` for broker-readable evidence captions; integrators can render either or both. value: run_id: c1d2a8e6-2c91-4b27-bf94-7c45a8e4d6f3 status: completed environment: live stage: COMPLETED attempt: 1 output: response_type: GAP_ANALYSIS profile_summary: policy_count: 2 named_insureds: - JOHN DOE summary: total_gaps: 1 high_severity_gaps: 1 medium_severity_gaps: 0 low_severity_gaps: 0 gaps: - id: gap_001 severity: HIGH category: INADEQUATE_LIMIT title: Dwelling coverage below replacement cost description: >- Your dwelling limit is $300,000 but the replacement cost estimate is $425,000. That's a $125,000 gap. recommendation: Increase dwelling coverage to at least $425,000. data_sources: - >- external_reports.property_data.replacement_cost_estimate_cents - current_portfolio.policies[0].coverages data_source_labels: - >- Replacement-cost estimate from property data (dollars) - Coverage limits on the customer's existing policy duration_ms: 22815 created_at: '2026-04-01T20:15:02.117Z' completed_at: '2026-04-01T20:15:24.932Z' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': description: Run not found. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: run_not_found message: Run not found '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/AuthUnavailable' components: schemas: RunStatusResponse: type: object required: - run_id - status - environment - attempt - created_at properties: run_id: type: string format: uuid description: Stable run identifier. engine_type: type: string description: Runtime engine type. Omitted on legacy rows without engine metadata. engine_version: type: string description: | 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' status: type: string enum: - queued - processing - completed - degraded - failed description: | Current run status. `queued` and `processing` are non-terminal: keep polling. `completed`, `degraded`, and `failed` 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. environment: type: string enum: - test - live description: Environment the run executed in. stage: type: string description: Last known pipeline stage (e.g. `EVALUATE`, `FILTER`). output: type: object additionalProperties: true description: Run summary. Present on completed runs. properties: enrichment: type: object description: Per-source enrichment outcome blocks keyed by handler kind. additionalProperties: $ref: '#/components/schemas/EnrichmentOutcomeBlock' diagnostic: oneOf: - type: string - type: 'null' description: Reason when no solutions are produced. degradation_reason: type: string enum: - no_requirements - no_offerings - no_combinations - input_quality - llm_degraded - enrichment_degraded - scoring_rule_failed - mixed - other description: | Stable string enum carried on `degraded` runs (and on placement runs that completed cleanly with no solutions). 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: `scoring_rule_failed` > `input_quality` > `llm_degraded` > `enrichment_degraded` > `other`. `mixed` is reserved for future use; it is defined so customer-side switches don't break if precedence is loosened later. requirement_count: type: integer description: Number of required lines evaluated. solutions_count: type: integer description: Number of ranked solutions generated. appetite_bucket: type: string description: >- Ranking strategy used (`coverage_first`, `cost_sensitive`, `balanced`, `simplicity`). top_label: oneOf: - type: string - type: 'null' description: >- Label of the top-ranked solution (e.g. `recommended`, `best_value`). top_score: oneOf: - type: number - type: 'null' description: Overall score for the top-ranked solution. duration_ms: type: integer description: Duration of the final execution attempt in milliseconds. total_duration_ms: type: integer description: Wall-clock milliseconds from creation to terminal completion. attempt: type: integer minimum: 0 description: >- Execution attempt count. A terminal value of 1 means no worker retry. error: type: string description: Error message on failed runs. error_details: type: object additionalProperties: true description: Structured failure details. trace_id: type: string pattern: ^[0-9a-f]{32}$ description: Trace identifier for support correlation. created_at: type: string format: date-time description: RFC 3339 timestamp when the run was created. completed_at: type: string format: date-time description: RFC 3339 timestamp when the run reached a terminal state. solutions: type: array description: Ranked solutions. Present on completed placement runs. items: $ref: '#/components/schemas/Solution' warnings: description: | Structured input-quality warnings. Present only when the released engine configuration enables warning exposure. oneOf: - type: object additionalProperties: true - type: array items: type: object additionalProperties: true Error: type: object required: - code - message properties: code: type: string description: | Stable snake_case error identifier. Safe to match programmatically. Known codes: `invalid_request`, `invalid_input`, `unauthorized`, `auth_unavailable`, `rate_limited`, `missing_run_id`, `invalid_run_id`, `run_not_found`, `invalid_offerings`, `missing_input`, `queue_unreachable`, `engine_not_found`, `engine_slug_conflict`, `engine_archived`, `invalid_engine_type`, `validation_error`, `webhook_not_found`, `webhook_limit_exceeded`, `invalid_url`, `invalid_events`, `invalid_description`, `invalid_auth_token`, `missing_endpoint_id`, `invalid_endpoint_id`, `missing_delivery_id`, `invalid_delivery_id`, `delivery_not_found`, `delivery_not_resendable`, `insufficient_capability`, `engine_version_required`, `engine_version_exact_required`, `engine_version_not_found`, `engine_version_invalid_format`, `engine_version_draft_requires_sandbox_key`, `engine_version_none_released`, `test_scenario_sandbox_only`, `test_scenario_forbidden`, `test_scenario_exact_version_required`, `test_scenario_version_not_supported`, `invalid_test_scenario`, `request_bound_exceeded`, and `run_cap_exceeded`. message: type: string description: Human-readable error message. May change between versions. details: description: | Optional request-specific details. Request-bound failures use the `RequestBoundDetails` object. Validation failures may use an array of field issues or another documented object. EnrichmentOutcomeBlock: type: object additionalProperties: false required: - kind description: | 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 may omit them, so strict consumers should 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. The enrichment hard deadline is 8 seconds; 5 seconds is the service objective, not a per-call guarantee. FEMA degraded and circuit-open diagnostics use bounded `details.upstream` values `google_geocoding` and `nfhl`. properties: kind: type: string example: fema_nfhl status: type: string enum: - succeeded - not_mapped - skipped - ambiguous - unavailable attempted: type: boolean description: >- False when no upstream attempt occurred, including a cache hit or pre-call skip. payload: type: object additionalProperties: true description: | 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. fetched_at: type: string format: date-time diagnostics: type: array items: type: object additionalProperties: true allOf: - if: properties: status: enum: - succeeded - not_mapped then: required: - payload - if: properties: status: enum: - skipped - ambiguous - unavailable then: not: required: - payload - if: properties: kind: const: fema_nfhl status: const: succeeded required: - kind - status then: properties: payload: required: - sfha - base_flood_elevation_feet properties: sfha: type: - boolean - 'null' Solution: type: object required: - id - offerings - requirements_met - provider_count - scorecard properties: id: type: string format: uuid description: Stable solution identifier within this run. offerings: type: array description: Offerings included in this solution package. items: $ref: '#/components/schemas/SolutionOffering' requirements_met: type: array items: type: string description: Requirement markers satisfied (e.g. `lob_home` in insurance domain). provider_count: type: integer description: Number of distinct providers in this solution. est_cost_low: type: integer description: Estimated annual cost, low end. est_cost_high: type: integer description: Estimated annual cost, high end. consolidation_discount: type: number description: | 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. bundle: $ref: '#/components/schemas/AppliedBundle' scorecard: $ref: '#/components/schemas/Scorecard' cluster_label: type: string description: | Solution label indicating where it excels: `recommended`, `best_value`, `best_coverage`, `simplest`. rank: type: integer description: Rank position (1 = best). SolutionOffering: type: object required: - id - provider_name - category description: Abbreviated offering reference within a ranked solution. properties: id: type: string description: >- Line-level offering identifier (matches an entry in the submitted `offerings`). provider_name: type: string description: Provider display name. category: type: string description: >- Requirement category (domain-specific, e.g. `home`, `auto`, `umbrella` for insurance). data_currency: allOf: - $ref: '#/components/schemas/DataCurrency' description: > 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. AppliedBundle: type: object description: | Present on a Solution when a carrier-supplied bundle was applied. Lists the offerings that bundle together, the carrier's joined annual premium, the standalone-premium sum, and the dollar-per-year savings. Omitted on standalone solutions. required: - offering_ids - joined_premium_annual - standalone_premium_annual - savings_annual properties: offering_ids: type: array items: type: string description: IDs of every offering that participates in the applied bundle. joined_premium_annual: type: integer minimum: 0 standalone_premium_annual: type: integer minimum: 0 savings_annual: type: integer minimum: 0 description: | `standalone_premium_annual` minus `joined_premium_annual`, clamped to zero when the carrier's bundled price meets or exceeds the standalone sum. Scorecard: type: object required: - overall_level additionalProperties: true description: | Evaluation scorecard. `overall_level` is always present. Dimension keys are configured per released engine version; the named properties below are the default placement dimensions, not an exhaustive set. properties: coverage_completeness: $ref: '#/components/schemas/Dimension' pricing_competitiveness: $ref: '#/components/schemas/Dimension' provider_quality: $ref: '#/components/schemas/Dimension' placement_likelihood: $ref: '#/components/schemas/Dimension' operational_simplicity: $ref: '#/components/schemas/Dimension' risk_alignment: $ref: '#/components/schemas/Dimension' overall_level: type: number description: | Raw weighted level across configured dimensions. Use the solution's emitted `rank`, not this value, as the ordering contract. DataCurrency: type: object description: > Freshness of the underlying source data for an offering loaded from a materialized (replicate-then-index) connection. Advisory only; it labels the result and never changes ranking. Present only for materialize-sourced offerings; omitted otherwise. properties: effective_year: type: integer description: The source schedule's effective business year, when known. effective_date: type: string format: date description: The product's effective date (YYYY-MM-DD), when known. stale: type: boolean description: > True when the source data is older than the freshness window (more than one year old) or undated. A stale offering should be presented with a caution that its rates may no longer be current. undated: type: boolean description: True when no effective year or date is known at all. Dimension: type: object required: - level - label - justification - method properties: level: type: integer minimum: 1 maximum: 4 description: Rating from 1 (best) to 4 (worst). label: type: string description: Human-readable label for this level. justification: type: string description: Reasoning for the assigned level. method: type: string enum: - deterministic - llm - fallback description: How this dimension was scored. responses: BadRequest: description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalidRequest: summary: Malformed JSON value: code: invalid_request message: Request body is not valid JSON invalidInput: summary: Input validation failed value: code: invalid_input message: Input failed validation details: - field: input.address.state message: address.state is required for placement runs. invalidOfferings: summary: Placement run missing offerings value: code: invalid_offerings message: Inline offerings failed validation details: - field: offerings message: >- Offerings are required for placement runs. Pass provider offerings in the top-level offerings array. Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: unauthorized message: Missing or invalid API key RateLimited: description: Rate limit exceeded. Retry after the window resets. headers: Retry-After: description: Seconds until the rate limit window resets. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: code: rate_limited message: Rate limit exceeded AuthUnavailable: description: API key authentication is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: auth_unavailable message: API key authentication is temporarily unavailable securitySchemes: BearerAuth: type: http scheme: bearer description: | Send the credential as `Authorization: Bearer `. 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`, and `converse:use`. Operation descriptions name the required capability. Grandfathered `nx_live_...` and `nx_test_...` keys retain their existing broad access during the compatibility window. ````