Traces

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.

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.

Get a thread’s traces

cURL

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

cURL

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

The trace object

object

The end-user message the turn started from (input.message).

object

What the agent understood: the detected intents and the guardrails outcome (passed, reason).

array

The decisions the agent took while handling the message — one entry per step.

Show decision fields

string

The kind of decision (e.g. a tool activation, a computation, a branch).

string

The tool involved, when the decision concerns one.

string

Outcome of the step; fail_reason explains failures.

object

Why the step ran: type, reasons, matched_objective.

object

The rule behind the decision, when one applies: code, type, action, reason.

array

Parameters the agent computed during the turn (code, title, scope).

array

Every rule evaluated: its code, whether it triggered, and the per-condition reason breakdown.

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.

{
  "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?"]
  }
}

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

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.

Get started

Messaging

Management

Get a thread’s traces

Get one interaction’s trace

The trace object

Traces on the management surface

​Get a thread’s traces

​Get one interaction’s trace

​The trace object

​Traces on the management surface

Get a thread’s traces

Get one interaction’s trace

The trace object

Traces on the management surface