Get Trace

Retrieve symbolic reasoning traces for Apollo-1 agent interactions.

v1Stable

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.

cURL

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

task_id · string · required

The task identifier (conversation thread).

Response

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

interaction_id · string

The interaction identifier (same as message ID).

intent · string

The parsed user intent from the message.

entities · object

Entities extracted and resolved from the conversation.

parameters_extracted · array

Parameters collected during this interaction.

rules_evaluated · array

All rules that were evaluated, including:

Show rule evaluation structure

rules_evaluated[].rule_id · string

The rule identifier.

rules_evaluated[].rule_type · string

Type of rule (policy, confirmation, authentication, conditional, sequencing).

rules_evaluated[].predicate · string

The symbolic predicate that was evaluated.

rules_evaluated[].result · string

Evaluation result: “allowed”, “blocked”, “requires_confirmation”, etc.

rules_evaluated[].reason · string

Human-readable explanation of why the rule fired or didn’t fire.

tools_considered · array

Tools the agent considered invoking for this interaction.

tools_invoked · array

Tools that were actually called, including parameters passed.

decision · string

The final decision made by the agent (e.g., “proceed”, “block_with_explanation”, “request_confirmation”).

200

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

---

Get Single Interaction Trace

Retrieve the trace for a specific interaction.

cURL

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

task_id · string · required

The task identifier.

interaction_id · string · required

The interaction/message identifier to trace.

Response

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

200

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

---

Code Examples

Node.js - All Traces

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`);
  }
});

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}`);

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")

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'])}")

---

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

401

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

404

{
  "error": "Not Found",
  "message": "Task not found: task_123"
}