Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nusomi.com/llms.txt

Use this file to discover all available pages before exploring further.

Replays re-execute a sealed session — exactly, guided, or partial. See replay concepts for modes.

​
Trigger a replay

POST /v1/replays

{
  "session_id": "ses_01HZ...",
  "mode": "guided",
  "from_frame": null,
  "model": "claude-opus-4-7",
  "budget_ms": 300000,
  "sandbox": "dry"
}

​
Body

FieldRequiredNotes
session_idyesSource session. Must be sealed.
modeyesexact | guided | partial.
from_frameonly for partialFrame id.
from_tagoptionalUse a tag as the anchor instead of from_frame.
modelonly for guidedDefaults to workspace setting.
budget_msoptionalWall-clock cap. Default 5 min.
sandboxoptionaldry (default) | live | staging:<env>.
metadataoptionalFree-form JSON, surfaced on the replay session.

​
Response 202

{
  "id": "rpl_01HZ...",
  "status": "queued",
  "session_id": "ses_01HZ...",
  "replay_session_id": null,
  "mode": "guided"
}

​
Get a replay

GET /v1/replays/{id}

{
  "id": "rpl_01HZ...",
  "status": "running",
  "session_id": "ses_01HZ...",
  "replay_session_id": "ses_01HZ...",
  "mode": "guided",
  "step_count": 14,
  "started_at": "2026-05-07T14:01:01Z",
  "finished_at": null,
  "outcome": null
}
status progresses queued → running → completed | diverged | failed | budget_exceeded.

​
Replay session

Once replay_session_id is set, that session can be queried like any other (events, frames, exports). Use it to verify the replay matched the original.

​
Stream replay progress

GET /v1/replays/{id}/stream
Accept: text/event-stream
Emits step events as the replay progresses, plus a final result event with the outcome.

​
Cancel a replay

POST /v1/replays/{id}/cancel
Idempotent. Marks the replay cancelled. Live-sandbox cancels make a best-effort to stop external side effects but cannot guarantee atomicity (e.g. a network request already in flight).

​
List replays

GET /v1/replays?session_id=ses_...&mode=guided
Supports the usual limit / cursor pagination.

​
Recovery

Recovery is a thin wrapper that finds the right from_frame for you and triggers a partial guided replay: 
POST /v1/recoveries

{
  "session_id": "ses_01HZ...",
  "mode": "guided",
  "max_attempts": 3
}
Returns the same shape as /v1/replays.