Decision & Execution Replay API

The Decision & Execution Replay API provides access to detailed workflow execution history including policy decisions, enabling debugging, compliance auditing, and performance analysis.

Overview

Every workflow execution is recorded with:

• Execution Summary: Overall status, timing, cost, and token usage
• Step Snapshots: Detailed per-step records with input/output, LLM provider, policies checked
• Timeline View: Ordered sequence of events for visualization
• Export Capability: Download complete execution records for compliance

Base URL: http://localhost:8081 (Orchestrator)

---

List Executions

GET /api/v1/executions

Retrieve a paginated list of execution summaries with optional filtering.

Request:

curl "http://localhost:8081/api/v1/executions?limit=10&offset=0&status=completed" \
  -H "X-Tenant-ID: my-org"

Query Parameters:

Parameter	Type	Description
limit	integer	Number of results (default: 50, max: 100)
offset	integer	Pagination offset (default: 0)
status	string	Filter by status: running, completed, failed
workflow_id	string	Filter by workflow name
start_time	string	Filter from timestamp (RFC3339)
end_time	string	Filter to timestamp (RFC3339)

Response (200 OK):

{
  "executions": [
    {
      "request_id": "exec-abc123",
      "workflow_name": "travel-planner",
      "status": "completed",
      "total_steps": 3,
      "completed_steps": 3,
      "total_tokens": 1250,
      "total_cost_usd": 0.0125,
      "started_at": "2026-01-03T10:00:00Z",
      "completed_at": "2026-01-03T10:00:05Z",
      "duration_ms": 5234,
      "org_id": "org-001",
      "tenant_id": "my-org",
      "user_id": "user-123"
    }
  ],
  "total": 150,
  "limit": 10,
  "offset": 0
}

---

Get Execution

GET /api/v1/executions/{id}

Retrieve a complete execution record including summary and all steps.

Request:

curl http://localhost:8081/api/v1/executions/exec-abc123 \
  -H "X-Tenant-ID: my-org"

Response (200 OK):

{
  "summary": {
    "request_id": "exec-abc123",
    "workflow_name": "travel-planner",
    "status": "completed",
    "total_steps": 3,
    "completed_steps": 3,
    "total_tokens": 1250,
    "total_cost_usd": 0.0125,
    "started_at": "2026-01-03T10:00:00Z",
    "completed_at": "2026-01-03T10:00:05Z",
    "duration_ms": 5234,
    "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-01-03T10:00:00Z",
      "completed_at": "2026-01-03T10:00: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": [...]
      },
      "policies_checked": ["pii-detection", "sql-injection"],
      "policies_triggered": []
    },
    {
      "step_index": 1,
      "step_name": "hotel-search",
      "status": "completed",
      "...": "..."
    },
    {
      "step_index": 2,
      "step_name": "synthesize",
      "status": "completed",
      "...": "..."
    }
  ]
}

---

Get Execution Steps

GET /api/v1/executions/{id}/steps

Retrieve all step snapshots for an execution.

Request:

curl http://localhost:8081/api/v1/executions/exec-abc123/steps \
  -H "X-Tenant-ID: my-org"

Response (200 OK):

[
  {
    "request_id": "exec-abc123",
    "step_index": 0,
    "step_name": "flight-search",
    "status": "completed",
    "started_at": "2026-01-03T10:00:00Z",
    "completed_at": "2026-01-03T10:00:01Z",
    "duration_ms": 1234,
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514",
    "tokens_in": 150,
    "tokens_out": 350,
    "cost_usd": 0.005,
    "policies_checked": ["pii-detection", "sql-injection"],
    "policies_triggered": []
  },
  {
    "step_index": 1,
    "step_name": "hotel-search",
    "...": "..."
  }
]

---

Get Specific Step

GET /api/v1/executions/{id}/steps/{stepIndex}

Retrieve a specific step snapshot with full input/output.

Request:

curl http://localhost:8081/api/v1/executions/exec-abc123/steps/0 \
  -H "X-Tenant-ID: my-org"

Response (200 OK):

{
  "request_id": "exec-abc123",
  "step_index": 0,
  "step_name": "flight-search",
  "status": "completed",
  "started_at": "2026-01-03T10:00:00Z",
  "completed_at": "2026-01-03T10:00:01Z",
  "duration_ms": 1234,
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "tokens_in": 150,
  "tokens_out": 350,
  "cost_usd": 0.005,
  "input": {
    "prompt": "Find direct flights from SFO to CDG under $1000 for June 1-7, 2026"
  },
  "output": {
    "flights": [
      {
        "airline": "Air France",
        "flight": "AF123",
        "price": 850,
        "departure": "2026-06-01T10:00:00Z"
      }
    ]
  },
  "policies_checked": ["pii-detection", "sql-injection", "rate-limit"],
  "policies_triggered": [],
  "approval_required": false
}

---

Get Timeline

GET /api/v1/executions/{id}/timeline

Retrieve a timeline view of execution events for visualization.

Request:

curl http://localhost:8081/api/v1/executions/exec-abc123/timeline \
  -H "X-Tenant-ID: my-org"

Response (200 OK):

[
  {
    "step_index": 0,
    "step_name": "flight-search",
    "status": "completed",
    "started_at": "2026-01-03T10:00:00Z",
    "completed_at": "2026-01-03T10:00:01Z",
    "duration_ms": 1234,
    "has_error": false,
    "has_approval": false
  },
  {
    "step_index": 1,
    "step_name": "hotel-search",
    "status": "completed",
    "started_at": "2026-01-03T10:00:01Z",
    "completed_at": "2026-01-03T10:00:02Z",
    "duration_ms": 1456,
    "has_error": false,
    "has_approval": false
  },
  {
    "step_index": 2,
    "step_name": "synthesize",
    "status": "completed",
    "started_at": "2026-01-03T10:00:03Z",
    "completed_at": "2026-01-03T10:00:05Z",
    "duration_ms": 2345,
    "has_error": false,
    "has_approval": false
  }
]

---

Export Execution

GET /api/v1/executions/{id}/export

Download a complete execution record for compliance or archival.

Request:

curl http://localhost:8081/api/v1/executions/exec-abc123/export \
  -H "X-Tenant-ID: my-org" \
  -o execution-export.json

Query Parameters:

Parameter	Type	Description
format	string	Export format: json (default)
include_input	boolean	Include step inputs (default: true)
include_output	boolean	Include step outputs (default: true)
include_policies	boolean	Include policy details (default: true)

Response Headers:

Content-Type: application/json
Content-Disposition: attachment; filename=execution-exec-abc123.json

Response (200 OK):

{
  "exported_at": "2026-01-03T12:00:00Z",
  "format": "json",
  "execution": {
    "summary": {
      "request_id": "exec-abc123",
      "workflow_name": "travel-planner",
      "...": "..."
    },
    "steps": [
      {
        "step_index": 0,
        "step_name": "flight-search",
        "input": {...},
        "output": {...},
        "policies_checked": [...],
        "...": "..."
      }
    ]
  }
}

---

Delete Execution

DELETE /api/v1/executions/{id}

Delete an execution and all associated step snapshots.

Request:

curl -X DELETE http://localhost:8081/api/v1/executions/exec-abc123 \
  -H "X-Tenant-ID: my-org"

Response (204 No Content):

No response body.

---

Data Model

Execution Summary

Field	Type	Description
request_id	string	Unique execution identifier
workflow_name	string	Name of the executed workflow
status	string	running, completed, failed
total_steps	integer	Total number of steps in workflow
completed_steps	integer	Number of completed steps
total_tokens	integer	Total tokens used (input + output)
total_cost_usd	number	Total LLM cost in USD
started_at	string	ISO8601 timestamp
completed_at	string	ISO8601 timestamp (null if running)
duration_ms	integer	Total execution time in milliseconds
error_message	string	Error message if failed
input_summary	object	Summarized input data
output_summary	object	Summarized output data
org_id	string	Organization identifier
tenant_id	string	Tenant identifier
user_id	string	User who initiated execution

Execution Snapshot (Step)

Field	Type	Description
request_id	string	Parent execution identifier
step_index	integer	Zero-based step position
step_name	string	Step name from workflow definition
status	string	running, completed, failed, paused
started_at	string	ISO8601 timestamp
completed_at	string	ISO8601 timestamp
duration_ms	integer	Step execution time
provider	string	LLM provider (for llm-call steps)
model	string	Model identifier
tokens_in	integer	Input tokens
tokens_out	integer	Output tokens
cost_usd	number	Step cost in USD
input	object	Full step input
output	object	Full step output
error_message	string	Error message if failed
policies_checked	array	List of policies evaluated
policies_triggered	array	List of policies that matched
approval_required	boolean	Whether HITL approval was required
approved_by	string	Approver email (if approved)
approved_at	string	Approval timestamp

---

Status Values

Execution Status

Status	Description
running	Execution in progress
completed	All steps completed successfully
failed	One or more steps failed

Step Status

Status	Description
pending	Step not yet started
running	Step currently executing
completed	Step finished successfully
failed	Step encountered an error
paused	Step awaiting approval (HITL)
skipped	Step skipped due to condition

---

Error Responses

HTTP Status	Error Code	Description
400	BAD_REQUEST	Invalid request parameters
404	NOT_FOUND	Execution or step not found
500	INTERNAL_ERROR	Server error

---

SDK Examples

All examples use the official AxonFlow SDKs. Full working examples are available in the execution-replay examples.

Go

Full example →

import axonflow "github.com/getaxonflow/axonflow-sdk-go"

client, _ := axonflow.NewClient(axonflow.AxonFlowConfig{
    AgentURL:        "http://localhost:8080",
    OrchestratorURL: "http://localhost:8081",
})
defer client.Close()

// List executions
listResult, _ := client.ListExecutions(&axonflow.ListExecutionsOptions{Limit: 10})
fmt.Printf("Total executions: %d\n", listResult.Total)

// Get execution details
execDetail, _ := client.GetExecution(executionID)
fmt.Printf("Status: %s, Steps: %d/%d\n",
    execDetail.Summary.Status, execDetail.Summary.CompletedSteps, execDetail.Summary.TotalSteps)

// Get timeline
timeline, _ := client.GetExecutionTimeline(executionID)

// Export for compliance
export, _ := client.ExportExecution(executionID, &axonflow.ExecutionExportOptions{
    IncludeInput: true, IncludeOutput: true,
})

Python

Full example →

from axonflow import AxonFlow, ListExecutionsOptions, ExecutionExportOptions

client = AxonFlow.sync(
    agent_url="http://localhost:8080",
    orchestrator_url="http://localhost:8081",
)

# List executions
list_result = client.list_executions(ListExecutionsOptions(limit=10))
print(f"Total executions: {list_result.total}")

# Get execution details
exec_detail = client.get_execution(execution_id)
print(f"Status: {exec_detail.summary.status}")

# Get timeline
timeline = client.get_execution_timeline(execution_id)

# Export for compliance
export = client.export_execution(
    execution_id,
    ExecutionExportOptions(include_input=True, include_output=True)
)

TypeScript

Full example →

import { AxonFlow } from "@axonflow/sdk";

const client = new AxonFlow({
    endpoint: "http://localhost:8080",
    orchestratorEndpoint: "http://localhost:8081",
});

// List executions
const listResult = await client.listExecutions({ limit: 10 });
console.log(`Total executions: ${listResult.total}`);

// Get execution details
const execDetail = await client.getExecution(executionId);
console.log(`Status: ${execDetail.summary.status}`);

// Get timeline
const timeline = await client.getExecutionTimeline(executionId);

// Export for compliance
const exportData = await client.exportExecution(executionId, {
    includeInput: true, includeOutput: true,
});

Java

Full example →

import com.getaxonflow.sdk.AxonFlow;
import com.getaxonflow.sdk.AxonFlowConfig;
import com.getaxonflow.sdk.types.executionreplay.*;

AxonFlowConfig config = AxonFlowConfig.builder()
    .agentUrl("http://localhost:8080")
    .orchestratorUrl("http://localhost:8081")
    .build();
AxonFlow client = AxonFlow.create(config);

// List executions
var listResult = client.listExecutions(ListExecutionsOptions.builder().setLimit(10));
System.out.println("Total executions: " + listResult.getTotal());

// Get execution details
var execDetail = client.getExecution(executionId);
System.out.println("Status: " + execDetail.getSummary().getStatus());

// Get timeline
var timeline = client.getExecutionTimeline(executionId);

// Export for compliance
var export = client.exportExecution(executionId,
    ExecutionExportOptions.builder().setIncludeInput(true).setIncludeOutput(true));

HTTP (curl)

Full example →

# List executions
curl "http://localhost:8081/api/v1/executions?limit=10" | jq .

# Get execution details
curl "http://localhost:8081/api/v1/executions/{id}" | jq .

# Get execution timeline
curl "http://localhost:8081/api/v1/executions/{id}/timeline" | jq .

# Export for compliance
curl "http://localhost:8081/api/v1/executions/{id}/export?include_input=true&include_output=true" \
  -o execution-export.json

---

Use Cases

Debugging Failed Executions

# Find failed executions
curl "http://localhost:8081/api/v1/executions?status=failed&limit=5" \
  -H "X-Tenant-ID: my-org"

# Get details of failed execution
curl http://localhost:8081/api/v1/executions/exec-failed-123 \
  -H "X-Tenant-ID: my-org"

# Check the specific failed step
curl http://localhost:8081/api/v1/executions/exec-failed-123/steps/2 \
  -H "X-Tenant-ID: my-org"

Cost Analysis

# Get recent executions with cost data
curl "http://localhost:8081/api/v1/executions?limit=100" \
  -H "X-Tenant-ID: my-org" | \
  jq '[.executions[].total_cost_usd] | add'

Compliance Audit

# Export all executions for a time period
for id in $(curl -s "http://localhost:8081/api/v1/executions?start_time=2026-01-01T00:00:00Z&end_time=2026-01-31T23:59:59Z" \
  -H "X-Tenant-ID: my-org" | jq -r '.executions[].request_id'); do
  curl "http://localhost:8081/api/v1/executions/$id/export" \
    -H "X-Tenant-ID: my-org" \
    -o "audit/$id.json"
done

---

Next Steps

• Multi-Agent Planning Overview - Learn about MAP workflows
• Audit Logging - Governance audit trail
• Workflow API - Execute workflows programmatically