Skip to main content
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

HeaderRequiredDescription
x-aui-api-keyYesYour 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:
​
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”).
[
  {
    "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. 
{
  "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

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

​
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

StatusDescription
401Missing or invalid x-aui-api-key header
404Task or interaction not found
403Insufficient permissions for the specified agent
401
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}
404
{
  "error": "Not Found",
  "message": "Task not found: task_123"
}