> ## Documentation Index
> Fetch the complete documentation index at: https://docs.invokehq.run/llms.txt
> Use this file to discover all available pages before exploring further.

# traces

> Every Invoke action returns a structured execution trace recording tool attempts, reconciliation decisions, blocked side effects, and policy events.

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

```json theme={null}
{
  "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](/concepts/execution-records) — the persistent object each trace is attached to
* [Reconciliation](/concepts/reconciliation) — the trace steps for unknown outcome resolution
* [Approvals](/concepts/approvals) — the trace steps for approval-bound actions