traces - Invoke

Every completed Invoke call returns an execution trace. The trace is a timestamped record of every control decision, tool attempt, reconciliation check, and policy event that occurred during execution. It is attached to the response and stored against the execution record.

What a trace contains

{
  "execution_id": "exec_abc123",
  "status": "reconciled",
  "final_outcome": "already_succeeded",
  "idempotency_key": "charge:cust_123:2400",
  "retry": "blocked",
  "trace": [
    {
      "step": "commit_record_created",
      "timestamp": "2026-05-25T10:00:00Z"
    },
    {
      "step": "tool_call_attempted",
      "timestamp": "2026-05-25T10:00:01Z",
      "detail": "stripe.charge_customer returned unknown outcome"
    },
    {
      "step": "outcome_reconciled",
      "timestamp": "2026-05-25T10:00:02Z",
      "detail": "live state confirms charge already succeeded"
    },
    {
      "step": "retry_blocked",
      "timestamp": "2026-05-25T10:00:02Z",
      "decision": "do_not_retry"
    },
    {
      "step": "trace_returned",
      "timestamp": "2026-05-25T10:00:02Z"
    }
  ]
}

Lifecycle trace steps

Every execution record moves through a defined sequence of trace steps:

Step	When it appears
`commit_record_created`	Always — before any external call
`tool_call_attempted`	Every time the tool is dispatched
`scope_check_failed`	When the agent ID or tool is outside registered policy
`outcome_reconciled`	When an unknown outcome is resolved
`retry_blocked`	When reconciliation returns `do_not_retry`
`approval_requested`	When an approval-bound tool is staged
`approval_granted`	When a reviewer approves
`approval_rejected`	When a reviewer rejects
`state_revalidated`	Before an approved action executes
`replan_required`	When live state has drifted
`trace_returned`	Always — final step

Using traces for debugging

When something unexpected happens — an action was blocked, a retry fired, a replan was triggered — the trace tells you exactly why. Every decision has a timestamp and a detail field explaining what Invoke checked and what it found. Access traces from:

The Invoke dashboard — browse by agent ID, execution ID, or time range
The API response — every invoke.call() response includes the trace inline
Execution records — traces are stored against the execution ID for later retrieval

Next steps

Execution Records — the persistent object each trace is attached to
Reconciliation — the trace steps for unknown outcome resolution
Approvals — the trace steps for approval-bound actions