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?
Full query parameters, response schemas, and status codes for every endpoint on this page are in the generated Orchestrator API reference, rendered from the published OpenAPI spec. Use the links in the table below to jump straight to an operation.
Endpoints
| Method | Path | Purpose | Reference |
|---|---|---|---|
GET | /api/v1/executions | List executions | listExecutions |
GET | /api/v1/executions/{id} | Get one execution | getExecution |
GET | /api/v1/executions/{id}/steps | List steps | getExecutionSteps |
GET | /api/v1/executions/{id}/steps/{stepIndex} | Get one step | getExecutionStep |
GET | /api/v1/executions/{id}/timeline | Timeline view | getExecutionTimeline |
GET | /api/v1/executions/{id}/export | Export execution | exportExecution |
DELETE | /api/v1/executions/{id} | Delete execution | deleteExecution |
Base URL: http://localhost:8080 through the Agent proxy, or http://localhost:8081 directly on the Orchestrator.
Listing and Filtering
GET /api/v1/executions (listExecutions) supports limit, offset, status, workflow_id, and RFC3339 start_time / end_time filters, and returns an executions array with total, limit, and offset pagination metadata.
curl "http://localhost:8080/api/v1/executions?status=failed&limit=20" \
-H "Authorization: Basic $(echo -n 'client-id:client-secret' | base64)"
Each execution summary includes 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} (getExecution) returns a summary plus a steps array of replay snapshots. 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.
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 (getExecutionTimeline) returns a step-oriented timeline. Two entry fields are worth calling out for triage tooling: has_error flags any step-level error, and has_approval tells you whether a human approval gate was involved in that step.
GET /api/v1/executions/{id}/export (exportExecution) accepts format (default json) plus include_input, include_output, and include_policies toggles (all default true). This export route is useful when incident review, internal audit, or regulated delivery teams need an artifact outside the live UI.
DELETE /api/v1/executions/{id} (deleteExecution) removes an execution snapshot set. Teams usually reserve that for retention management or cleanup workflows, not day-to-day debugging.
Related Docs
Operational Readiness Checklist
Before relying on this page in a production rollout, pair it with the core operations docs:
- Deployment Mode Matrix for self-hosted, Evaluation, Enterprise, SaaS, and In-VPC fit
- Failure Modes And Recovery for degraded-provider, connector, approval, and runtime behavior
- Capacity Planning for sizing and growth signals
- Community vs Evaluation vs Enterprise for limits, support surfaces, and upgrade triggers
