> ## 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 Defensibility Packet

> The portable sourcing chain for a completed run (identity, output, provenance, enrichment calls, timeline). Model-call prompt bodies are withheld; calls are attested by stage.

This route exposes a broader restricted-data surface than ordinary polling. A
scoped key must have `runs:defensibility:read`, must be bound to the run's
engine, and must belong to the run's canonical named environment. The default
runtime capability set does not include packet access.

## Contents

The version 1 packet can contain:

* run identity, submitter reference, engine/config lineage, timestamps, status,
  warnings, structured errors, and cost rollup
* the customer-visible output and per-element provenance map
* redacted external-call request and response evidence
* the run event timeline and its lineage fields
* aggregate model call, token, cache, and cost summaries
* a redaction count and explicit provenance coverage marker

Raw model-call prompt and completion blobs are withheld. Each model call remains
attested by pipeline stage with a null body in the customer-facing packet.
External-call evidence, output, provenance, warnings, event attributes, and
submitter labels may contain restricted data. Store and transmit the packet
accordingly.

## Errors

| Status | Code                                 | Meaning                                                                              |
| ------ | ------------------------------------ | ------------------------------------------------------------------------------------ |
| `400`  | `missing_run_id` or `invalid_run_id` | The path ID is absent or is not a UUID.                                              |
| `401`  | `unauthorized`                       | The bearer credential is missing or invalid.                                         |
| `403`  | `insufficient_capability`            | The scoped key lacks `runs:defensibility:read`.                                      |
| `404`  | `run_not_found`                      | The run is absent or outside the key's organization, environment, or engine binding. |
| `500`  | `internal_error`                     | Packet evidence could not be loaded completely. No partial packet is returned.       |

## Retention

The packet is assembled from run-bound evidence. Non-flagged runs and their
packet evidence use the platform's 90-day default retention window and purge
together. Authorized internal preservation flags can retain a run longer.


## OpenAPI

````yaml GET /api/v1/runs/{run_id}/defensibility-packet
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/runs/{run_id}/defensibility-packet:
    get:
      tags:
        - Engines
      summary: Get Run Defensibility Packet
      description: |
        Return the portable sourcing chain for a completed run: a single
        document a client, board, or auditor can read to see how the output
        was reached. Scoped partner keys require the separate
        `runs:defensibility:read` capability plus matching engine and canonical
        named-environment bindings. A run outside any of those scopes returns
        `404`.

        The packet bundles the run identity and lineage, the customer-visible
        `output`, the per-element `provenance` map (with a
        `provenance_coverage` marker that reads `none` for pre-provenance
        runs so an absent map never looks sourced-clean), the external
        (enrichment) calls that fed the run, the event timeline, and an LLM
        cost/token summary.

        Model calls are attested by `stage` so the chain is complete, but the
        prompt and completion bodies are withheld. That prompt-engineering
        detail is the engine's implementation IP and is never part of the
        customer contract.
      operationId: getRunDefensibilityPacket
      parameters:
        - in: path
          name: run_id
          required: true
          schema:
            type: string
            format: uuid
          example: bcb87157-0bfc-404d-a120-7f5c9cd01037
      responses:
        '200':
          description: The customer-facing defensibility packet.
          content:
            application/json:
              schema:
                type: object
                required:
                  - version
                  - run
                  - provenance_coverage
                  - model_calls
                  - external_calls
                  - events
                  - redaction
                properties:
                  version:
                    type: string
                    example: '1'
                  run:
                    type: object
                    description: >-
                      Run identity and lineage (id, engine, version, status,
                      timestamps).
                  output:
                    type: object
                    description: The customer-visible output of the run.
                  provenance:
                    type: object
                    description: >-
                      Per-element provenance map, present when the run recorded
                      one.
                  provenance_coverage:
                    type: string
                    enum:
                      - present
                      - none
                    description: >-
                      `none` for runs predating provenance capture; an absent
                      map must not read as sourced-clean.
                  model_calls:
                    type: array
                    description: >-
                      Stage attestation that a model call ran, without the
                      prompt or completion body.
                    items:
                      type: object
                      properties:
                        stage:
                          type: string
                        blob_type:
                          type: string
                  external_calls:
                    type: array
                    description: Enrichment calls that fed the run, with their payloads.
                    items:
                      type: object
                      properties:
                        stage:
                          type: string
                        blob_type:
                          type: string
                        blob:
                          type: object
                  events:
                    type: array
                    description: The run event timeline.
                    items:
                      type: object
                  llm_summary:
                    type: object
                    description: Aggregate model cost and token usage for the run.
                  redaction:
                    type: object
                    properties:
                      fields_redacted:
                        type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Run not found in this org.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: run_not_found
                message: run not found
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  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
    Forbidden:
      description: Scoped key does not have the capability required by this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: insufficient_capability
            message: API key does not have permission for this action
    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 <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.

````