Decision & Execution Replay API
The replay API gives engineers a detailed view of execution history for governed requests and multi-agent workflows. It is the API you reach for when you need to answer questions like:
- Which step failed?
- Which provider and model were used?
- Which policies were checked or triggered?
- What did a workflow do before a bad output or a compliance event?
Overview
Verified routes:
| Method | Path | Purpose |
|---|---|---|
GET | /api/v1/executions | List executions |
GET | /api/v1/executions/{id} | Get one execution |
GET | /api/v1/executions/{id}/steps | List steps |
GET | /api/v1/executions/{id}/steps/{stepIndex} | Get one step |
GET | /api/v1/executions/{id}/timeline | Timeline view |
GET | /api/v1/executions/{id}/export | Export execution |
DELETE | /api/v1/executions/{id} | Delete execution |
Base URL: http://localhost:8080 through the Agent proxy, or http://localhost:8081 directly on the Orchestrator.
Listing and Filtering
Verified list query parameters:
| Query param | Notes |
|---|---|
limit | Default 50 |
offset | Default 0 |
status | Execution status |
workflow_id | Workflow filter |
start_time | RFC3339 |
end_time | RFC3339 |
Response wrapper:
{
"executions": [],
"total": 0,
"limit": 50,
"offset": 0
}
Each execution summary includes verified fields like request_id, workflow_name, status, total_steps, completed_steps, started_at, completed_at, duration_ms, total_tokens, total_cost_usd, and tenant or org context when available.
Execution Details
GET /api/v1/executions/{id} returns:
{
"summary": {},
"steps": []
}
The steps array is made of verified replay snapshots containing fields such as:
request_idstep_indexstep_namestatusstarted_atcompleted_atduration_msinputoutputprovidermodeltokens_intokens_outcost_usdpolicies_checkedpolicies_triggerederror_message
That combination is what makes this API so valuable for senior engineers debugging sophisticated agent workflows. It shows not just that something failed, but exactly where, under which provider, with which governance events attached.
Example detail response:
{
"summary": {
"request_id": "exec-abc123",
"workflow_name": "travel-planner",
"status": "completed",
"total_steps": 3,
"completed_steps": 3,
"started_at": "2026-03-29T11:55:00Z",
"completed_at": "2026-03-29T11:55:05Z",
"duration_ms": 5234,
"total_tokens": 1250,
"total_cost_usd": 0.0125,
"tenant_id": "tenant-123",
"input_summary": {
"query": "Plan a trip to Paris"
},
"output_summary": {
"itinerary": "Day 1: Flight at 9am..."
}
},
"steps": [
{
"request_id": "exec-abc123",
"step_index": 0,
"step_name": "flight-search",
"status": "completed",
"started_at": "2026-03-29T11:55:00Z",
"completed_at": "2026-03-29T11:55:01Z",
"duration_ms": 1234,
"provider": "anthropic",
"model": "claude-sonnet-4-20250514",
"tokens_in": 150,
"tokens_out": 350,
"cost_usd": 0.005,
"input": {
"prompt": "Find flights to Paris"
},
"output": {
"flights": ["AF123"]
},
"policies_checked": ["pii-detection", "rate-limit"],
"policies_triggered": [],
"retry_count": 0
}
]
}
Step snapshots are especially useful because they preserve both execution state and governance metadata:
| Field | Why it matters |
|---|---|
status, started_at, completed_at, duration_ms | Debugging latency and failure timing |
provider, model, tokens_in, tokens_out, cost_usd | Provider-level behavior and cost analysis |
policies_checked, policies_triggered | Governance traceability |
error_message, retry_count | Retry and failure diagnosis |
Timeline and Export
GET /api/v1/executions/{id}/timeline returns a timeline array with step-oriented entries such as step_index, step_name, status, started_at, completed_at, duration_ms, has_error, and has_approval.
GET /api/v1/executions/{id}/export accepts:
| Query param | Default |
|---|---|
format | json |
include_input | true |
include_output | true |
include_policies | true |
This export route is useful when incident review, internal audit, or regulated delivery teams need an artifact outside the live UI.
Timeline entries include:
| Field | Notes |
|---|---|
step_index, step_name | Step identity |
status | pending, running, completed, failed, or paused |
started_at, completed_at, duration_ms | Timing data |
has_error | Any step-level error occurred |
has_approval | Whether a human approval gate was involved |
DELETE /api/v1/executions/{id} removes an execution snapshot set. Teams usually reserve that for retention management or cleanup workflows, not day-to-day debugging.
