Forking Executions

What is Forking?

Forking lets you branch from any step in a recorded execution and replay with modified input. Think of it as git bisect for AI agents - find where things went wrong, try a different path.

Creating a Fork

From the Dashboard

1. Open any trace in the trace viewer
2. Click the fork icon on any span in the left panel
3. Modify the input JSON in the dialog
4. Click "Create Fork"
5. The fork executes and creates a new trace from the branch point

From the API

curl -X POST https://api.retraceai.tech/api/v1/forks \
  -H "x-retrace-key: rt_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "trace_id": "uuid-of-original-trace",
    "fork_point_span_id": "uuid-of-span-to-fork-from",
    "name": "Try different prompt",
    "modified_input": {
      "messages": [{"role": "user", "content": "modified prompt here"}]
    }
  }'

Then replay the fork:

curl -X POST https://api.retraceai.tech/api/v1/forks/{fork_id}/replay \
  -H "x-retrace-key: rt_live_..."

Divergence Score

Every fork produces a divergence score (0.0 to 1.0) showing how much the new path differs:

Use Cases

• Debug failed runs: Fork from the step before the error, change the input
• A/B test prompts: Fork from the same point with different prompts, compare outputs
• Explore alternatives: Try different tool combinations without re-running from scratch
• Sensitivity analysis: Quantify how input changes affect agent behavior

[!NOTE] Forking copies all spans before the fork point into a new trace. The fork itself only re-executes from the branch point forward. Cost is proportional to the remaining steps, not the full trace.

Retrace AI

Fork replay is powered by Retrace AI — no external API keys needed. Your Retrace API key (rt_live_...) authenticates all AI requests automatically.

AI usage counts toward your plan's Retrace AI request limit:

• Free: 100 requests/mo
• Pro: 10,000 requests/mo
• Enterprise: Unlimited

[!NOTE] Provider keys are available on all plans.

SDK Callback Replay

For advanced use cases, you can replay a fork in your own agent code and submit the results back to Retrace:

1. Create a fork via the API
2. Initialize the fork with POST /api/v1/forks/:id/replay
3. Run the modified LLM call in your own code
4. Submit the replay spans via POST /api/v1/forks/:id/replay/callback

curl -X POST https://api.retraceai.tech/api/v1/forks/:id/replay/callback \
  -H "Authorization: Bearer rt_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "spans": [
      {
        "span_type": "llm_call",
        "name": "My custom replay",
        "model": "gemini-2.5-flash",
        "input": {"messages": [{"role": "user", "content": "modified prompt"}]},
        "output": "Replay result from my own infrastructure",
        "input_tokens": 150,
        "output_tokens": 80,
        "cost": 0.0015,
        "duration_ms": 1200
      }
    ]
  }'

[!TIP] SDK callback replay lets you use any model provider, run custom tool calls, or execute replays in your own infrastructure.