> ## 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. # Submit Run Outcome > Record what happened after a run (viewed, accepted, overridden, or placement outcome). This is the real-world signal the flywheel learns from. ## OpenAPI ````yaml POST /api/v1/engines/{engine_slug}/runs/{run_id}/outcomes 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 markets 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. - name: Converse description: The raw stateless conversational model turn (caller-owned state). - name: Conversations description: >- Conversation instances (orchestrators over engines) and their managed conversations, turns, annotations, evals, and exports. paths: /api/v1/engines/{engine_slug}/runs/{run_id}/outcomes: post: tags: - Engines summary: Submit Run Outcome description: | Record what happened after a run. This is the real-world signal the flywheel learns from. Each event carries a caller-supplied `event_id` for idempotent replay, an `event_type`, and a typed `payload` whose shape depends on the event type. Event types: - `viewed`: a human looked at the result. - `accepted`: the recommended option was taken. - `overridden`: a different option was chosen, with a `reason_code` (one of `broker_preference`, `customer_preference`, `price`, `coverage_gap`, `carrier_appetite`, `other`). - `placement_outcome`: the downstream result, with `status` one of `quoted`, `bound`, `lost`, `declined`. Idempotency. Re-posting the same `event_id` with an identical payload returns `200 OK` (a no-op replay). A first write returns `201 Created`. Re-using an `event_id` with a different payload is rejected with `409 Conflict` (`event_id_reused`). operationId: submitOutcome parameters: - $ref: '#/components/parameters/EngineSlug' - in: path name: run_id required: true schema: type: string format: uuid example: bcb87157-0bfc-404d-a120-7f5c9cd01037 requestBody: required: true content: application/json: schema: type: object required: - event_id - event_type - payload properties: event_id: type: string description: >- Caller-supplied idempotency key. Re-using it with the same payload is a no-op replay. event_type: type: string enum: - viewed - accepted - overridden - placement_outcome payload: type: object description: >- Typed payload whose fields depend on event_type. See the examples. examples: accepted: summary: Recommended option accepted value: event_id: 7e1d2c3b-1111-4444-8888-aaaaaaaaaaaa event_type: accepted payload: accepted_at: '2026-06-17T12:00:00Z' accepted_carrier_id: prog overridden: summary: A different option was chosen value: event_id: 9a2b3c4d-2222-4444-8888-bbbbbbbbbbbb event_type: overridden payload: overridden_at: '2026-06-17T12:05:00Z' chosen_carrier_id: trvl reason_code: price reason_text: Cheaper for equivalent coverage. placement_outcome: summary: Downstream placement result value: event_id: c4d5e6f7-3333-4444-8888-cccccccccccc event_type: placement_outcome payload: outcome_at: '2026-06-20T09:00:00Z' status: bound carrier_id: trvl responses: '200': description: >- Idempotent replay. The same event_id and payload was already recorded. content: application/json: schema: type: object required: - event_id - status properties: event_id: type: string status: type: string enum: - recorded example: event_id: 7e1d2c3b-1111-4444-8888-aaaaaaaaaaaa status: recorded '201': description: Outcome recorded. content: application/json: schema: type: object required: - event_id - status properties: event_id: type: string status: type: string enum: - recorded example: event_id: 7e1d2c3b-1111-4444-8888-aaaaaaaaaaaa status: recorded '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': description: Run not found in this org and environment. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: run_not_found message: Run not found '409': description: The event_id was already used with a different payload. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: event_id_reused message: event_id already used with a different payload '429': $ref: '#/components/responses/RateLimited' components: parameters: EngineSlug: name: engine_slug in: path required: true description: Engine identifier slug (e.g. `default`). schema: type: string 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 schemas: 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`, `instance_not_found`, `instance_slug_conflict`, `instance_archived`, `instance_follows_canonical`, `instance_not_published`, `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. 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`, `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. ````