> ## 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.

# Traces

> Inspect the agent's reasoning: what it understood, which rules fired, what it decided.

Every interaction produces a **trace** — a structured record of the agent's
reasoning for that turn: the input it saw, what it understood, the decisions it
took, the parameters it computed, the rules it evaluated, and the response it
gave.

Two ways to fetch traces on the messaging surface:

| Endpoint                                               | Returns                                 |
| ------------------------------------------------------ | --------------------------------------- |
| `GET /messaging/v1/threads/{threadId}/trace`           | Every interaction's trace in the thread |
| `GET /messaging/v1/interactions/{interactionId}/trace` | One interaction's trace                 |

The `interactionId` is the `message.id` from a
[send-message response](/api/messaging/send-messages).

<Tip>
  On the WebSocket session, the final `message` envelope embeds the same trace
  as `data.trace_info` when the session was opened with `include_trace=true`.
</Tip>

***

## Get a thread's traces

```bash cURL theme={"dark"}
curl "https://api-v3.aui.io/apollo-api/messaging/v1/threads/{threadId}/trace" \
  -H "Authorization: Bearer <access_token>"
```

Returns an array of trace objects, one per interaction, oldest first.

## Get one interaction's trace

```bash cURL theme={"dark"}
curl "https://api-v3.aui.io/apollo-api/messaging/v1/interactions/{interactionId}/trace" \
  -H "Authorization: Bearer <access_token>"
```

***

## The trace object

<ResponseField name="input" type="object">
  The end-user message the turn started from (`input.message`).
</ResponseField>

<ResponseField name="understanding" type="object">
  What the agent understood: the detected `intents` and the `guardrails`
  outcome (`passed`, `reason`).
</ResponseField>

<ResponseField name="decisions" type="array">
  The decisions the agent took while handling the message — one entry per
  step.

  <Expandable title="decision fields">
    <ResponseField name="decisions[].type" type="string">
      The kind of decision (e.g. a tool activation, a computation, a branch).
    </ResponseField>

    <ResponseField name="decisions[].tool" type="string">
      The tool involved, when the decision concerns one.
    </ResponseField>

    <ResponseField name="decisions[].status" type="string">
      Outcome of the step; `fail_reason` explains failures.
    </ResponseField>

    <ResponseField name="decisions[].trigger" type="object">
      Why the step ran: `type`, `reasons`, `matched_objective`.
    </ResponseField>

    <ResponseField name="decisions[].rule" type="object">
      The rule behind the decision, when one applies: `code`, `type`,
      `action`, `reason`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="computed_parameters" type="array">
  Parameters the agent computed during the turn (`code`, `title`, `scope`).
</ResponseField>

<ResponseField name="rules_evaluations" type="array">
  Every rule evaluated: its `code`, whether it `triggered`, and the
  per-condition `reason` breakdown.
</ResponseField>

<ResponseField name="response" type="object">
  How the agent answered: the response `type` and `message`, follow-up
  `suggestions`, what it was `asking_for`, any `block_message`, and rendered
  `jsx_widgets`.
</ResponseField>

<ResponseExample>
  ```json 200 theme={"dark"}
  {
    "input": { "message": "I want to dispute a charge from May 30th" },
    "understanding": {
      "intents": ["dispute_charge"],
      "guardrails": { "passed": true }
    },
    "decisions": [
      {
        "type": "rule_check",
        "rule": {
          "code": "dispute_window",
          "type": "policy",
          "action": "block",
          "reason": "Charge is older than the 8-day dispute window"
        },
        "status": "blocked"
      }
    ],
    "computed_parameters": [
      { "code": "transaction_date", "title": "Transaction date", "scope": "conversation" }
    ],
    "rules_evaluations": [
      {
        "code": "dispute_window",
        "triggered": true,
        "reason": [
          { "passed": false, "trigger_type": "condition", "condition": { "method": "date_diff", "operation": "lte" } }
        ]
      }
    ],
    "response": {
      "type": "answer",
      "message": "Our dispute window is 8 days, so that charge can't be disputed — here are your options.",
      "suggestions": ["What other options do I have?"]
    }
  }
  ```
</ResponseExample>

<Info>
  Trace fields are additive: new fields may appear as the reasoning engine
  evolves, so treat unknown fields as informational rather than errors.
</Info>

***

## Traces on the management surface

The same traces are available under `/management/v1` for back-office tooling —
`GET /management/v1/threads/{threadId}/trace` and
`GET /management/v1/interactions/{interactionId}/trace` — authenticated with a
management credential. See [Management → Threads](/api/management/threads).