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

# Decision Replay

> Re-evaluate past production decisions against a candidate version and see exactly what would change — before you deploy.

## What is Decision Replay?

Decision Replay takes a real past execution — identified by its trace ID — and re-evaluates its exact input facts against a candidate version. The stored decision is the baseline and is never re-evaluated; only the candidate runs, and every external effect (webhooks, notifications, events) is mocked, so nothing fires twice.

The result is a decision diff: whether the decision changed, which rules fired on each side, and how the resulting effects differ.

<Info>
  **Dry Run vs Simulation vs Replay** — [Dry Run](/guides/dry-run) evaluates facts you type by hand. [Impact Simulation](/guides/simulation) runs a dataset or a slice of history in bulk and reports aggregate statistics. Decision Replay answers the sharpest question of the three: *what would this exact production decision have been under the new version?*
</Info>

## When to Use

* **Before deploying a fix** — a customer was priced wrong last Tuesday. Replay that trace against the fixed version and confirm the decision now comes out right.
* **Incident forensics** — pair with [Decision Provenance](/guides/decision-provenance) to understand *why* a decision happened, then verify the fix with a replay.
* **Blast radius before rollout** — replay a whole date window against the candidate and count how many past decisions would change.

## Two Modes

|           | Single replay                   | Window replay                                |
| --------- | ------------------------------- | -------------------------------------------- |
| Scope     | One trace                       | A date window of past executions             |
| Execution | Synchronous                     | Async job (submit and poll)                  |
| Billing   | Free (TPS throttle only)        | Billed per replayed record (`REPLAY` metric) |
| Roles     | Admin, User, Viewer, API client | Viewer cannot submit or cancel               |

## Replaying a Single Decision

### Console

Open **Decision Replay** in the console, pick a past execution and a candidate version, and run. The diff view shows fired rules and effect changes side by side.

### CLI

```bash theme={null}
lexq replay decision --trace-id <traceId> --version-id <candidateVersionId>
```

### API

```bash theme={null}
curl -X POST "https://api.lexq.io/api/v1/partners/replay/decisions" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "traceId": "8f3c1a2e-1d44-4c1b-9a3e-0f5b7c2d9e10",
    "candidateVersionId": "b2ba29d8-c5b2-400c-a6a1-26d3a5840f7c"
  }'
```

### Response

```json theme={null}
{
  "result": "SUCCESS",
  "data": {
    "traceId": "8f3c1a2e-1d44-4c1b-9a3e-0f5b7c2d9e10",
    "decisionChanged": true,
    "determinism": "DETERMINISTIC",
    "effectChanges": [ "…" ],
    "baselineFired": [ "…" ],
    "candidateFired": [ "…" ]
  }
}
```

`decisionChanged` is the headline. `baselineFired` and `candidateFired` list the rules that fired on each side, and `effectChanges` details how the resulting effects differ. `determinism` is a property of the candidate version itself: whether identical inputs are guaranteed to produce identical decisions.

<Info>
  Replaying a trace against the **same version it originally ran on** must yield `decisionChanged: false`. If it does not, the version is non-deterministic — worth knowing before you trust any diff produced from it.
</Info>

## Window Replay — Blast Radius

Window replay re-evaluates every execution in a date range against the candidate and measures how many decisions would change.

### Submit

```bash theme={null}
lexq replay start --version-id <candidateVersionId> --from 2026-07-01 --to 2026-07-07 --max-records 1000
```

```bash theme={null}
curl -X POST "https://api.lexq.io/api/v1/partners/replay/jobs" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "candidateVersionId": "b2ba29d8-c5b2-400c-a6a1-26d3a5840f7c",
    "from": "2026-07-01",
    "to": "2026-07-07",
    "maxRecords": 1000
  }'
```

### Poll

```bash theme={null}
lexq replay get --id <jobId>
```

While the job is `RUNNING`, `progress` climbs to 100. On `COMPLETED`, the response carries a `summary` of how many decisions changed and `changedSamples` for inspection. If the window held more executions than `maxRecords`, `capped` is `true` — the result is a sample, not the full window.

`lexq replay list` shows job history, and `lexq replay cancel --id <jobId>` cooperatively cancels a `PENDING` or `RUNNING` job.

<Warning>
  Window replay is **billed per replayed record** on the `REPLAY` metric, with a hard cap of 50,000 records per job. External effects are always mocked in both modes — a replay never sends a webhook, notification, or event.
</Warning>

<Warning>
  A trace can only be replayed while its version still exists. LexQ's audit retention refuses to delete a version that has recorded executions (`AN-028`), so this holds for any trace produced after retention was enabled.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Decision Provenance" icon="fingerprint" href="/guides/decision-provenance">
    Trace who authored, published, and deployed the rules behind a decision.
  </Card>

  <Card title="Impact Simulation" icon="chart-line" href="/guides/simulation">
    Bulk what-if analysis with aggregate statistics before you deploy.
  </Card>
</CardGroup>