---
title: "Fork from any step. Replay the future. — Retrace"
description: "Fork an AI agent run at any step, change the input, and cascade-replay the whole function. Compare runs with a side-by-side diff and cost and latency deltas."
canonical: "https://retraceai.tech/features/fork-replay"
last-updated: 2026-08-26
format: text/markdown
---

# Fork from any step. Replay the future.

Branch a recorded run at the exact step that broke, change the input, and re-execute the entire agent down the new path, then compare the two runs side by side.

## What it does

- **Cascade replay** — Forking re-runs the full function from the chosen step forward, so a changed input actually propagates into every downstream call, not just one isolated model call.
- **Reproducible re-execution** — Server-side replays re-run the model with deterministic settings so results are as repeatable as providers allow, and recorded runs can be replayed back exactly from the tape.
- **Pay only for what changes** — Steps before the fork point are served from the original recording at no token cost, you're billed only for the part of the run that actually diverges.
- **Side-by-side diff** — Compare the original and forked runs step by step, with cost and latency deltas highlighted down to the first point where they diverge.
- **Verified replay** — Accelerated replays are checked against a fresh execution; if the output diverges beyond a threshold, Retrace falls back to a full run so debugging fidelity is never silently lost.
- **Replay player & cost preview** — Scrub any run like a video, and preview what a fork will cost (with a breakdown of where the savings come from) before you run it.

## Examples

Fork at a step, replay it, then inspect the diff.

```terminal
retrace forks create --trace <id> --span <id> --input "grounded prompt"
retrace forks replay <id> --wait
retrace forks diff <id> --json
```


## REST API

- `POST /api/v1/forks: create a fork from a span`
- `POST /api/v1/forks/:id/replay: re-execute the fork`
- `GET /api/v1/forks/:id/diff: original vs fork diff`

## Related

- HTML page: https://retraceai.tech/features/fork-replay
- Documentation: https://docs.retraceai.tech
- OpenAPI specification: https://retraceai.tech/openapi.json
- Authentication for agents: https://retraceai.tech/auth.md