Replay API

Session replay endpoint. Reconstructs a session step by step with cumulative context at each point.

GET /api/sessions/:id/replay

Returns a ReplayState for the given session, containing ordered steps with paired events and reconstructed context.

Path Parameters

Parameter	Type	Description
id	string	Session ID

Query Parameters

Parameter	Type	Default	Range	Description
offset	number	0	≥ 0	Start at this step index
limit	number	1000	1–5000	Maximum steps to return
eventTypes	string	—	—	Comma-separated event type filter (e.g., llm_call,tool_call)
includeContext	boolean	true	—	Include reconstructed context per step

Valid Event Types

session_started, session_ended, llm_call, llm_response, tool_call, tool_response, error, decision, observation, custom

Response (200)

{
  "session": {
    "id": "ses_abc123",
    "agentId": "my-agent",
    "status": "completed",
    "startedAt": "2026-02-08T10:30:00.000Z",
    "endedAt": "2026-02-08T10:32:15.000Z"
  },
  "chainValid": true,
  "totalSteps": 42,
  "steps": [
    {
      "index": 0,
      "event": {
        "id": "evt_001",
        "eventType": "session_started",
        "timestamp": "2026-02-08T10:30:00.000Z",
        "payload": {}
      },
      "pairedEvent": null,
      "pairDurationMs": null,
      "context": {
        "eventIndex": 0,
        "totalEvents": 42,
        "cumulativeCostUsd": 0.0,
        "elapsedMs": 0,
        "eventCounts": { "session_started": 1 },
        "llmHistory": [],
        "toolResults": [],
        "pendingApprovals": [],
        "errorCount": 0,
        "warnings": []
      }
    },
    {
      "index": 1,
      "event": {
        "id": "evt_002",
        "eventType": "llm_call",
        "timestamp": "2026-02-08T10:30:01.000Z",
        "payload": { "provider": "openai", "model": "gpt-4o" }
      },
      "pairedEvent": {
        "id": "evt_003",
        "eventType": "llm_response",
        "timestamp": "2026-02-08T10:30:02.200Z"
      },
      "pairDurationMs": 1200,
      "context": {
        "eventIndex": 1,
        "totalEvents": 42,
        "cumulativeCostUsd": 0.012,
        "elapsedMs": 1000,
        "eventCounts": { "session_started": 1, "llm_call": 1 },
        "llmHistory": [
          {
            "callId": "call_001",
            "provider": "openai",
            "model": "gpt-4o",
            "messages": [],
            "response": "...",
            "costUsd": 0.012,
            "latencyMs": 1200
          }
        ],
        "toolResults": [],
        "pendingApprovals": [],
        "errorCount": 0,
        "warnings": []
      }
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 1000,
    "hasMore": false
  },
  "summary": {
    "totalCost": 0.0342,
    "totalDurationMs": 135000,
    "totalLlmCalls": 4,
    "totalToolCalls": 6,
    "totalErrors": 0,
    "models": ["gpt-4o"],
    "tools": ["read_file", "search_code", "write_file"]
  }
}

Response Fields

Field	Type	Description
session	object	Session metadata
chainValid	boolean	Whether the event hash chain is valid
totalSteps	number	Total steps in the full replay
steps	array	Ordered replay steps (may be paginated)
steps[].index	number	0-based step index
steps[].event	object	The event at this step
steps[].pairedEvent	object|null	Paired event (e.g., tool_call → tool_response)
steps[].pairDurationMs	number|null	Duration between paired events (ms)
steps[].context	object	Reconstructed context at this step
steps[].context.cumulativeCostUsd	number	Total cost up to this step
steps[].context.elapsedMs	number	Time since session start
steps[].context.eventCounts	object	Event type counts up to this step
steps[].context.llmHistory	array	LLM conversation history (capped at 50)
steps[].context.toolResults	array	Tool call results available at this step
steps[].context.pendingApprovals	array	Approval statuses
steps[].context.errorCount	number	Cumulative error count
steps[].context.warnings	array	Warnings triggered at this step
pagination	object	Pagination info
pagination.hasMore	boolean	Whether more steps are available
summary	object	Session-level summary

Caching

Replay states are cached server-side in an LRU cache:

• Max entries: 100
• TTL: 10 minutes
• LLM history cap: 50 entries per step (memory guard)

Errors

Status	Condition
400	Invalid query parameter
404	Session not found