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

> Retrieve symbolic reasoning traces for Apollo-1 agent interactions.

<div style={{ display: 'flex', gap: '8px', marginBottom: '16px' }}>
  <span style={{ background: '#22C55E', color: '#fff', padding: '2px 10px', borderRadius: '12px', fontSize: '13px', fontWeight: 500 }}>v1</span>
  <span style={{ background: 'rgba(129,105,255,0.15)', color: '#8169FF', padding: '2px 10px', borderRadius: '12px', fontSize: '13px', fontWeight: 500 }}>Stable</span>
</div>

Traces provide complete visibility into Apollo-1's symbolic reasoning: intents parsed, entities resolved, rules evaluated, parameters extracted, and decisions made. Every interaction produces a trace that records the computation in full.

***

## Get All Task Traces

Retrieve traces for all interactions in a conversation thread.

```bash cURL theme={null}
curl "https://api.aui.io/v1/messaging/tasks/task_123/trace-info" \
  -H "x-aui-api-key: your-api-key"
```

### GET `/v1/messaging/tasks/{task_id}/trace-info`

**Base URL:** `https://api.aui.io`

#### Headers

| Header          | Required | Description  |
| --------------- | -------- | ------------ |
| `x-aui-api-key` | Yes      | Your API key |

#### Path Parameters

<ParamField path="task_id" type="string" required>
  The task identifier (conversation thread).
</ParamField>

#### Response

Returns an array of trace objects, one per interaction in the thread. Each trace contains:

<ResponseField name="interaction_id" type="string">
  The interaction identifier (same as message ID).
</ResponseField>

<ResponseField name="intent" type="string">
  The parsed user intent from the message.
</ResponseField>

<ResponseField name="entities" type="object">
  Entities extracted and resolved from the conversation.
</ResponseField>

<ResponseField name="parameters_extracted" type="array">
  Parameters collected during this interaction.
</ResponseField>

<ResponseField name="rules_evaluated" type="array">
  All rules that were evaluated, including:

  <Expandable title="rule evaluation structure">
    <ResponseField name="rules_evaluated[].rule_id" type="string">
      The rule identifier.
    </ResponseField>

    <ResponseField name="rules_evaluated[].rule_type" type="string">
      Type of rule (policy, confirmation, authentication, conditional, sequencing).
    </ResponseField>

    <ResponseField name="rules_evaluated[].predicate" type="string">
      The symbolic predicate that was evaluated.
    </ResponseField>

    <ResponseField name="rules_evaluated[].result" type="string">
      Evaluation result: "allowed", "blocked", "requires\_confirmation", etc.
    </ResponseField>

    <ResponseField name="rules_evaluated[].reason" type="string">
      Human-readable explanation of why the rule fired or didn't fire.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="tools_considered" type="array">
  Tools the agent considered invoking for this interaction.
</ResponseField>

<ResponseField name="tools_invoked" type="array">
  Tools that were actually called, including parameters passed.
</ResponseField>

<ResponseField name="decision" type="string">
  The final decision made by the agent (e.g., "proceed", "block\_with\_explanation", "request\_confirmation").
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  [
    {
      "interaction_id": "msg_507f1f77bcf86cd799439011",
      "intent": "dispute_charge",
      "entities": {
        "transaction_id": "txn_abc123",
        "transaction_date": "2026-05-30",
        "transaction_amount": 99.99,
        "days_since_transaction": 10
      },
      "parameters_extracted": [
        "transaction_date",
        "transaction_id"
      ],
      "rules_evaluated": [
        {
          "rule_id": "rule_dispute_window",
          "rule_type": "policy",
          "predicate": "today - txn.date <= 8 days",
          "result": "blocked",
          "reason": "Transaction is 10 days old, exceeds 8-day dispute window"
        }
      ],
      "tools_considered": [
        "create_dispute",
        "get_transaction_details"
      ],
      "tools_invoked": [
        {
          "tool": "get_transaction_details",
          "parameters": {
            "transaction_id": "txn_abc123"
          },
          "result": "success"
        }
      ],
      "decision": "block_with_explanation"
    },
    {
      "interaction_id": "msg_507f1f77bcf86cd799439012",
      "intent": "view_recent_transactions",
      "entities": {
        "date_range": "last_30_days"
      },
      "parameters_extracted": [],
      "rules_evaluated": [],
      "tools_considered": [
        "list_transactions"
      ],
      "tools_invoked": [
        {
          "tool": "list_transactions",
          "parameters": {
            "limit": 10,
            "days": 30
          },
          "result": "success"
        }
      ],
      "decision": "proceed"
    }
  ]
  ```
</ResponseExample>

***

## Get Single Interaction Trace

Retrieve the trace for a specific interaction.

```bash cURL theme={null}
curl "https://api.aui.io/v1/messaging/tasks/task_123/interactions/msg_abc/trace-info" \
  -H "x-aui-api-key: your-api-key"
```

### GET `/v1/messaging/tasks/{task_id}/interactions/{interaction_id}/trace-info`

#### Path Parameters

<ParamField path="task_id" type="string" required>
  The task identifier.
</ParamField>

<ParamField path="interaction_id" type="string" required>
  The interaction/message identifier to trace.
</ParamField>

#### Response

Returns a single trace object (same structure as above) for the specified interaction.

<ResponseExample>
  ```json 200 theme={null}
  {
    "interaction_id": "msg_507f1f77bcf86cd799439011",
    "intent": "dispute_charge",
    "entities": {
      "transaction_id": "txn_abc123",
      "transaction_date": "2026-05-30",
      "transaction_amount": 99.99,
      "days_since_transaction": 10
    },
    "parameters_extracted": [
      "transaction_date",
      "transaction_id"
    ],
    "rules_evaluated": [
      {
        "rule_id": "rule_dispute_window",
        "rule_type": "policy",
        "predicate": "today - txn.date <= 8 days",
        "result": "blocked",
        "reason": "Transaction is 10 days old, exceeds 8-day dispute window"
      }
    ],
    "tools_considered": [
      "create_dispute",
      "get_transaction_details"
    ],
    "tools_invoked": [
      {
        "tool": "get_transaction_details",
        "parameters": {
          "transaction_id": "txn_abc123"
        },
        "result": "success"
      }
    ],
    "decision": "block_with_explanation"
  }
  ```
</ResponseExample>

***

## Code Examples

<CodeGroup>
  ```javascript Node.js - All Traces theme={null}
  const response = await fetch(
    "https://api.aui.io/v1/messaging/tasks/task_123/trace-info",
    {
      headers: {
        "x-aui-api-key": "your-api-key"
      }
    }
  );

  const traces = await response.json();
  console.log(`Found ${traces.length} interactions`);

  // Analyze rule evaluations
  traces.forEach(trace => {
    const blockedRules = trace.rules_evaluated.filter(r => r.result === "blocked");
    if (blockedRules.length > 0) {
      console.log(`Interaction ${trace.interaction_id} had ${blockedRules.length} blocking rules`);
    }
  });
  ```

  ```javascript Node.js - Single Trace theme={null}
  const taskId = "task_123";
  const interactionId = "msg_abc";

  const response = await fetch(
    `https://api.aui.io/v1/messaging/tasks/${taskId}/interactions/${interactionId}/trace-info`,
    {
      headers: {
        "x-aui-api-key": "your-api-key"
      }
    }
  );

  const trace = await response.json();
  console.log(`Intent: ${trace.intent}`);
  console.log(`Decision: ${trace.decision}`);
  console.log(`Rules evaluated: ${trace.rules_evaluated.length}`);
  ```

  ```python Python - All Traces theme={null}
  import requests

  response = requests.get(
      "https://api.aui.io/v1/messaging/tasks/task_123/trace-info",
      headers={"x-aui-api-key": "your-api-key"}
  )

  traces = response.json()
  print(f"Found {len(traces)} interactions")

  # Analyze rule evaluations
  for trace in traces:
      blocked_rules = [r for r in trace["rules_evaluated"] if r["result"] == "blocked"]
      if blocked_rules:
          print(f"Interaction {trace['interaction_id']} had {len(blocked_rules)} blocking rules")
  ```

  ```python Python - Single Trace theme={null}
  import requests

  task_id = "task_123"
  interaction_id = "msg_abc"

  response = requests.get(
      f"https://api.aui.io/v1/messaging/tasks/{task_id}/interactions/{interaction_id}/trace-info",
      headers={"x-aui-api-key": "your-api-key"}
  )

  trace = response.json()
  print(f"Intent: {trace['intent']}")
  print(f"Decision: {trace['decision']}")
  print(f"Rules evaluated: {len(trace['rules_evaluated'])}")
  ```
</CodeGroup>

***

## Understanding Traces

### White-Box Traceability

Every turn produces a trace that records the symbolic computation in full. Apollo-1's trace is not a generated explanation—it's the actual computation, recorded as it happens. The runtime cannot decide one thing and trace another, because the decision and the trace are the same object.

### Trace Components

**Intent Parsing**: How the user's message was interpreted and mapped to a symbolic intent.

**Entity Resolution**: What values were extracted from the conversation and how they map to your domain entities.

**Rule Evaluation**: Which predicates fired, which blocked actions, and why. Evaluation is deterministic—given the same state, the same rules fire the same way.

**Parameter Extraction**: What information was collected to fulfill the request.

**Tool Invocation**: Which tools were considered, which were called, with what parameters, and what they returned.

**Decision**: The final action taken by the agent based on the symbolic computation.

### Debugging with Traces

Traces let you diagnose failures to the exact point where perception diverged from intent:

* **Misclassified intent**: The agent understood a different intent than the user meant
* **Missing entity**: A required value wasn't extracted from the conversation
* **Rule blocked action**: A predicate evaluated false and prevented the tool call
* **Tool failure**: A tool was invoked but returned an error

Each failure resolves to a specific layer that owns it, making fixes surgical rather than speculative.

***

## Errors

| Status | Description                                      |
| ------ | ------------------------------------------------ |
| `401`  | Missing or invalid `x-aui-api-key` header        |
| `404`  | Task or interaction not found                    |
| `403`  | Insufficient permissions for the specified agent |

```json 401 theme={null}
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}
```

```json 404 theme={null}
{
  "error": "Not Found",
  "message": "Task not found: task_123"
}
```