> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aui.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get an interaction's trace

> The reasoning trace of a single interaction, resolved by its id.



## OpenAPI

````yaml https://api-v3.aui.io/apollo-api/openapi.json get /management/v1/interactions/{interactionId}/trace
openapi: 3.1.0
info:
  title: Apollo API
  description: >-
    Build conversational experiences on your agents and manage them
    programmatically.


    The API has two surfaces:


    - **Messaging** (`/messaging/v1`) — send end-user messages to your agent and
    read conversations back. Replies are available as a single JSON response, a
    Server-Sent Events token stream (`POST /messaging/v1/messages/stream`), or a
    bidirectional WebSocket session (see the companion AsyncAPI document at
    `/asyncapi.yaml`).

    - **Management** (`/management/v1`) — manage agents, their versions,
    projects, and conversation threads.


    **Authentication** — exchange your publishable key for a short-lived access
    token at `POST /management/v1/auth/token`, then send it as `Authorization:
    Bearer <access_token>`. Management endpoints also accept an organization API
    key via the `x-organization-api-key` header.


    **Errors** — every failure returns `{"error": {"code", "message",
    "request_id", "details"}}`. Branch on the stable `code`; include
    `request_id` when contacting support.
  version: 0.1.0
servers:
  - url: https://api-v3.aui.io/apollo-api
security: []
tags:
  - name: Auth
    description: >-
      Exchange a credential for a short-lived access token — start here. Send
      the token as `Authorization: Bearer <access_token>` on every other
      endpoint (management endpoints also accept an organization API key via the
      `x-organization-api-key` header).
  - name: Messaging
    description: >-
      Talk to your agent: send end-user messages (JSON reply or SSE token
      stream), rerun an interaction, and read a conversation's messages and
      reasoning traces. Threads are created automatically on the first message —
      pass the returned `thread_id` to continue a conversation.
  - name: Channels
    description: >-
      Reach end users on WhatsApp and SMS: send the opening message and bind the
      recipient's phone number to a conversation thread; replies flow through
      the same thread.
  - name: Threads
    description: >-
      Conversation threads: list and filter them, fetch one with its transcript
      and traces, and update its title.
  - name: Agents
    description: Create and manage the agents in a project.
  - name: Agent Versions
    description: >-
      An agent's configuration versions: list and inspect them, and publish a
      new live version.
  - name: Projects
    description: Projects group your agents within an organization.
  - name: Health
    description: Service liveness.
paths:
  /management/v1/interactions/{interactionId}/trace:
    get:
      tags:
        - Threads
      summary: Get an interaction's trace
      description: The reasoning trace of a single interaction, resolved by its id.
      operationId: get_interaction_trace
      parameters:
        - name: interactionId
          in: path
          required: true
          schema:
            type: string
            pattern: ^[0-9a-fA-F]{24}$
            title: Interactionid
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Trace'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Conflict
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unprocessable Content
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal Server Error
      security:
        - bearerAuth: []
        - organizationApiKey: []
components:
  schemas:
    Trace:
      properties:
        input:
          anyOf:
            - $ref: '#/components/schemas/TraceInput'
            - type: 'null'
        understanding:
          anyOf:
            - $ref: '#/components/schemas/TraceUnderstanding'
            - type: 'null'
        decisions:
          anyOf:
            - items:
                $ref: '#/components/schemas/TraceDecision'
              type: array
            - type: 'null'
          title: Decisions
        computed_parameters:
          anyOf:
            - items:
                $ref: '#/components/schemas/TraceComputedParameter'
              type: array
            - type: 'null'
          title: Computed Parameters
        response:
          anyOf:
            - $ref: '#/components/schemas/TraceResponse'
            - type: 'null'
        rules_evaluations:
          anyOf:
            - items:
                $ref: '#/components/schemas/TraceRuleEvaluation'
              type: array
            - type: 'null'
          title: Rules Evaluations
      type: object
      title: Trace
      description: The published, scrubbed reasoning trace for one interaction.
    ErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      type: object
      required:
        - error
      title: ErrorResponse
      description: The single envelope every Apollo error response conforms to.
    TraceInput:
      properties:
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
          description: The end-user's message
      type: object
      title: TraceInput
    TraceUnderstanding:
      properties:
        intents:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Intents
        guardrails:
          anyOf:
            - $ref: '#/components/schemas/TraceGuardrails'
            - type: 'null'
      type: object
      title: TraceUnderstanding
    TraceDecision:
      properties:
        type:
          anyOf:
            - type: string
            - type: 'null'
          title: Type
        tool:
          anyOf:
            - type: string
            - type: 'null'
          title: Tool
        parent_tool:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent Tool
        track_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Track Id
        status:
          anyOf:
            - type: string
            - type: 'null'
          title: Status
        check_status:
          anyOf:
            - type: string
            - type: 'null'
          title: Check Status
        trigger:
          anyOf:
            - $ref: '#/components/schemas/TraceTrigger'
            - type: 'null'
        trigger_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Trigger Type
        rule:
          anyOf:
            - $ref: '#/components/schemas/TraceRule'
            - type: 'null'
        text:
          anyOf:
            - type: string
            - type: 'null'
          title: Text
        fail_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Fail Reason
        computation:
          anyOf:
            - type: string
            - type: 'null'
          title: Computation
        output_param:
          anyOf:
            - type: string
            - type: 'null'
          title: Output Param
        output_title:
          anyOf:
            - type: string
            - type: 'null'
          title: Output Title
        qualified:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Qualified
        matched_branch:
          anyOf:
            - type: string
            - type: 'null'
          title: Matched Branch
      type: object
      title: TraceDecision
      description: One decision the agent took while handling the message.
    TraceComputedParameter:
      properties:
        code:
          anyOf:
            - type: string
            - type: 'null'
          title: Code
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        scope:
          anyOf:
            - type: string
            - type: 'null'
          title: Scope
      type: object
      title: TraceComputedParameter
    TraceResponse:
      properties:
        type:
          anyOf:
            - type: string
            - type: 'null'
          title: Type
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
        suggestions:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Suggestions
        question_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Question Reason
        asking_for:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Asking For
        block_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Block Message
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
        jsx_widgets:
          anyOf:
            - items:
                $ref: '#/components/schemas/TraceJsxWidget'
              type: array
            - type: 'null'
          title: Jsx Widgets
      type: object
      title: TraceResponse
    TraceRuleEvaluation:
      properties:
        code:
          anyOf:
            - type: string
            - type: 'null'
          title: Code
        triggered:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Triggered
        reason:
          anyOf:
            - items:
                $ref: '#/components/schemas/TraceRuleReason'
              type: array
            - type: 'null'
          title: Reason
      type: object
      title: TraceRuleEvaluation
    ErrorBody:
      properties:
        code:
          type: string
          title: Code
          description: >-
            Stable, namespaced machine code clients branch on (e.g. "not_found"
            or "agents.not_found"). THE branch point -- open/extensible,
            append-only.
        message:
          type: string
          title: Message
          description: >-
            Human-readable explanation. NOT part of the contract; may change
            anytime. Clients must never parse or branch on this.
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Request Id
          description: Trace id for support correlation.
        details:
          anyOf:
            - items:
                $ref: '#/components/schemas/ErrorDetail'
              type: array
            - type: 'null'
          title: Details
          description: Optional structured sub-errors (e.g. per-field validation failures).
      type: object
      required:
        - code
        - message
      title: ErrorBody
      description: |-
        The error body an end user receives when interacting with Apollo.

        ``code`` is the stable, machine-readable branch point clients switch on.
        ``message`` is human-readable and explicitly NOT part of the contract --
        it may change at any time and must never be parsed.
    TraceGuardrails:
      properties:
        passed:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Passed
        reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Reason
      type: object
      title: TraceGuardrails
    TraceTrigger:
      properties:
        type:
          anyOf:
            - type: string
            - type: 'null'
          title: Type
        reasons:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Reasons
        matched_objective:
          anyOf:
            - type: string
            - type: 'null'
          title: Matched Objective
      type: object
      title: TraceTrigger
    TraceRule:
      properties:
        type:
          anyOf:
            - type: string
            - type: 'null'
          title: Type
        action:
          anyOf:
            - type: string
            - type: 'null'
          title: Action
        reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Reason
        code:
          anyOf:
            - type: string
            - type: 'null'
          title: Code
      type: object
      title: TraceRule
    TraceJsxWidget:
      properties:
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        category:
          anyOf:
            - type: string
            - type: 'null'
          title: Category
        rendered_jsx:
          anyOf:
            - type: string
            - type: 'null'
          title: Rendered Jsx
        is_recommended:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Recommended
        index:
          anyOf:
            - type: integer
            - type: 'null'
          title: Index
      type: object
      title: TraceJsxWidget
    TraceRuleReason:
      properties:
        passed:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Passed
        trigger_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Trigger Type
        condition:
          anyOf:
            - $ref: '#/components/schemas/TraceCondition'
            - type: 'null'
      type: object
      title: TraceRuleReason
    ErrorDetail:
      properties:
        field:
          anyOf:
            - type: string
            - type: 'null'
          title: Field
        message:
          type: string
          title: Message
      type: object
      required:
        - message
      title: ErrorDetail
      description: A single structured sub-error (e.g. one field's validation failure).
    TraceCondition:
      properties:
        method:
          anyOf:
            - type: string
            - type: 'null'
          title: Method
        operation:
          anyOf:
            - type: string
            - type: 'null'
          title: Operation
      type: object
      title: TraceCondition
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Access token from `POST /management/v1/auth/token` (publishable-key
        exchange) or a login session. Publishable-key tokens are agent-scoped
        and serve the messaging surface; login tokens also serve management.
    organizationApiKey:
      type: apiKey
      in: header
      name: x-organization-api-key
      description: >-
        Organization API key — alternative to a Bearer token on the management
        surface.

````