API reference

Replays

One tag: method, path, summary, auth, and scopes. Request and response fields ship in this page — expand a row to read the contract.

Browse docs

Endpoints

POST

/api/v1/replays Agent Token

Create a replay

replays:write

Description

Creates a replay from a trace for debugging and analysis, including optional variant labels and config overrides. Replay.status is queued | running | completed | failed.

Auth

Agent Token

Required Scopes

replays:write

Request Body

Field	Type	Required	Description
workflow_target_id	string	No	Workflow target UUID. Falls back to source trace's target. Required if source trace has no workflow_target_id.
trace_id	string	Yes	UUID of the trace to replay
workflow_version_id	string	No	Optional workflow version override
config_overrides	object	No	Raw workflow config overrides merged before replay execution
model_override	string	No	Shortcut override merged into config_overrides.model
prompt_override	string	No	Shortcut override merged into config_overrides.prompt
source_context_override	object	No	Overrides for the source context (gateway context) used during replay
source_trace_id	string	No	Alias for trace_id
variant_label	string	No	Human-readable label for the replay variant

Responses

201

Replay created

Returns: Replay

Response Body

Field	Type	Required	Description
id	string	Yes	Replay UUID
status	string (queued, running, completed, failed)	Yes	Stored status. Cancel never writes cancelled.
started_at	datetime (ISO 8601)	No	When execution started
inserted_at	datetime (ISO 8601)	Yes	Record insertion timestamp
updated_at	datetime (ISO 8601)	Yes	Record update timestamp
job_id	integer	No	Oban job id
error_payload	object	Yes	Replay error payload. Cancel sets code to cancelled.
workflow_target_id	string	No	Workflow target UUID
duration_ms	integer	No	Duration in milliseconds
output_payload	object	Yes	Replay output payload
last_activity_at	datetime (ISO 8601)	No	Last recorded activity
total_cost	number	No	Attributed replay cost
workflow_version_id	string	No	Workflow version UUID
config_overrides	object	Yes	Merged config overrides
source_context_override	object	Yes	Source context override used during replay
source_trace_id	string	Yes	Source trace UUID
variant_label	string	No	Replay variant label
comparison	object	Yes	Source vs generated comparison
finished_at	datetime (ISO 8601)	No	When execution finished
generated_trace_id	string	No	Generated replay trace UUID

Example

{
  "comparison": {
    "changed": false
  },
  "config_overrides": {
    "model": "gpt-4.1"
  },
  "duration_ms": 1840,
  "error_payload": {},
  "finished_at": "2026-03-15T10:00:03Z",
  "generated_trace_id": "7c8d9e0f-1234-4abc-b567-890123456789",
  "id": "e5f6a7b8-9012-4cde-f345-678901234567",
  "inserted_at": "2026-03-15T10:00:00Z",
  "job_id": 18421,
  "last_activity_at": "2026-03-15T10:00:03Z",
  "output_payload": {
    "result": "ok"
  },
  "source_context_override": {},
  "source_trace_id": "6646e3ff-8f2f-4204-ad5c-f4ebc1830f9e",
  "started_at": "2026-03-15T10:00:01Z",
  "status": "completed",
  "total_cost": 0.04,
  "updated_at": "2026-03-15T10:00:03Z",
  "variant_label": "prompt-v2",
  "workflow_target_id": "4ce4d170-e6d5-4118-8f4d-fac69dc099ea",
  "workflow_version_id": "d0b91d0c-0f4b-4a28-8d9d-ccf0c427d6e8"
}

404

Trace not found

POST

/api/v1/replays/:id/cancel Agent Token

Cancel a replay

replays:write

Description

Cancels a queued or running replay. Replay.status is only queued | running | completed | failed; cancel writes status failed with error_payload.code "cancelled". A cancelled status is never stored.

Auth

Agent Token

Required Scopes

replays:write

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Replay UUID

Responses

200

Replay cancelled. status is failed; error_payload.code is "cancelled".

Returns: Replay

Response Body

Field	Type	Required	Description
id	string	Yes	Replay UUID
status	string (queued, running, completed, failed)	Yes	Stored status. Cancel never writes cancelled.
started_at	datetime (ISO 8601)	No	When execution started
inserted_at	datetime (ISO 8601)	Yes	Record insertion timestamp
updated_at	datetime (ISO 8601)	Yes	Record update timestamp
job_id	integer	No	Oban job id
error_payload	object	Yes	Replay error payload. Cancel sets code to cancelled.
workflow_target_id	string	No	Workflow target UUID
duration_ms	integer	No	Duration in milliseconds
output_payload	object	Yes	Replay output payload
last_activity_at	datetime (ISO 8601)	No	Last recorded activity
total_cost	number	No	Attributed replay cost
workflow_version_id	string	No	Workflow version UUID
config_overrides	object	Yes	Merged config overrides
source_context_override	object	Yes	Source context override used during replay
source_trace_id	string	Yes	Source trace UUID
variant_label	string	No	Replay variant label
comparison	object	Yes	Source vs generated comparison
finished_at	datetime (ISO 8601)	No	When execution finished
generated_trace_id	string	No	Generated replay trace UUID

Example

{
  "comparison": {
    "error": "cancelled"
  },
  "config_overrides": {
    "model": "gpt-4.1"
  },
  "duration_ms": 1840,
  "error_payload": {
    "cancelled": true,
    "code": "cancelled",
    "reason": "User cancelled"
  },
  "finished_at": "2026-03-15T10:00:03Z",
  "generated_trace_id": null,
  "id": "e5f6a7b8-9012-4cde-f345-678901234567",
  "inserted_at": "2026-03-15T10:00:00Z",
  "job_id": 18421,
  "last_activity_at": "2026-03-15T10:00:03Z",
  "output_payload": {},
  "source_context_override": {},
  "source_trace_id": "6646e3ff-8f2f-4204-ad5c-f4ebc1830f9e",
  "started_at": "2026-03-15T10:00:01Z",
  "status": "failed",
  "total_cost": 0.04,
  "updated_at": "2026-03-15T10:00:03Z",
  "variant_label": "prompt-v2",
  "workflow_target_id": "4ce4d170-e6d5-4118-8f4d-fac69dc099ea",
  "workflow_version_id": "d0b91d0c-0f4b-4a28-8d9d-ccf0c427d6e8"
}

400

cannot_cancel — the replay is not queued or running

404

Replay not found