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

# Replay API

> Re-run historical traces against a new manifest. Confirms behavioral impact of an agent change empirically.

The Replay API runs historical traces back through your agent under a different manifest version. Use it to **empirically confirm** whether a change actually breaks the things the [regression check](/guides/regression-check) flagged as risky — or to recover traces that the pre-deploy check marked `medium_risk` (where structural reasoning can only say "might differ").

## When to use replay

<CardGroup cols={2}>
  <Card title="Confirm a structural prediction" icon="check-double">
    The regression check said `medium_risk` (model swap, prompt rewrite). Replay actually runs the affected traces through the new manifest so you can see the new outputs side-by-side with the originals.
  </Card>

  <Card title="Reproduce a flaky bug" icon="bug">
    A trace failed in production. Replay it against the same manifest to see if the failure is deterministic, then against your fix branch to verify it's resolved.
  </Card>

  <Card title="Build training data from drift" icon="database">
    Replay flagged-for-repair traces against a known-good manifest, then export as JSONL for SFT. This is the bridge between trace history and the [Datasets API](/api-reference/datasets/overview).
  </Card>

  <Card title="Re-score with a new evaluator" icon="scale-balanced">
    Add a new `@eval` function. Replay traces under the same manifest to re-score them without re-running the agent.
  </Card>
</CardGroup>

## Lifecycle

```mermaid theme={null}
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#f5f5f4','primaryBorderColor':'#a8a29e','primaryTextColor':'#44403c','lineColor':'#a8a29e'}}}%%
flowchart TD
    A["GET /traces?agent_name=...<br/>collect the trace_ids to replay"] --> B["POST /replay/batches<br/>returns batch_id with N tasks"]
    B --> C["tasks fan out to workers<br/>each runs original input vs new manifest"]
    C --> D["POST /replay/tasks/{task_id}/submit<br/>worker submits new output + score"]
    D --> E["GET /replay/batches/{batch_id}<br/>track progress"]
    E --> F["GET /replay/batches/{batch_id}/export-dpo<br/>pull results as JSONL"]
```

## Endpoints at a glance

| Method | Path                                           | Purpose                                                                      |
| ------ | ---------------------------------------------- | ---------------------------------------------------------------------------- |
| `POST` | `/api/v1/replay/batches`                       | Create a new replay batch from an explicit list of `trace_ids`               |
| `GET`  | `/api/v1/replay/batches/{batch_id}`            | Track progress + retrieve aggregate results                                  |
| `GET`  | `/api/v1/replay/export`                        | Export the prompts of traces needing replay as JSONL (requires `agent_name`) |
| `GET`  | `/api/v1/replay/batches/{batch_id}/export-dpo` | Export a finished batch's results as DPO preference pairs                    |
| `POST` | `/api/v1/replay/tasks/{task_id}/submit`        | Submit a single task's result (called by replay workers)                     |

## Quick start

```python theme={null}
import httpx
from datetime import datetime, timedelta, timezone

headers = {"Authorization": "Bearer dai_sk_..."}

# 1. Select the traces yourself — every "drop"-verdict trace from the last 7 days.
#    There is no server-side trace selection: the batch endpoint takes explicit ids.
since = (datetime.now(timezone.utc) - timedelta(days=7)).isoformat()
traces = httpx.get(
    "https://api.decimal.ai/api/v1/traces",
    headers=headers,
    params={
        "agent_name": "support-agent",
        "eval_verdict": "drop",
        "started_at_from": since,
        "limit": 100,
    },
).json()["traces"]

# 2. Create a replay batch — re-run those traces against manifest v4.
resp = httpx.post(
    "https://api.decimal.ai/api/v1/replay/batches",
    headers=headers,
    json={
        "trace_ids": [t["id"] for t in traces],
        "target_manifest_id": "mfst_v4_abc",
    },
)
batch_id = resp.json()["batch_id"]

# 3. Poll for completion
import time
while True:
    status = httpx.get(
        f"https://api.decimal.ai/api/v1/replay/batches/{batch_id}",
        headers=headers,
    ).json()
    if status["status"] == "completed":
        break
    time.sleep(5)

print(f"{status['passed_tasks']} passed · {status['failed_tasks']} failed of {status['total_tasks']}")
```

## Related

* [Replay Guide](/guides/replay) — when to replay vs. when to repair
* [Regression Check](/guides/regression-check) — the pre-deploy companion that flags candidates for replay
* [Datasets API](/api-reference/datasets/overview) — export replay results as training data