Replays

Overview

A replay creates a queued comparison job and a generated replay trace while preserving the source trace. It is useful for debugging and variant analysis, but it can repeat external behavior, so the source must be replayable and the selected target/context must be reviewed before scheduling.

Source and generated traces remain separate

The replay retains a reference to the original source trace and writes the new execution to a separate generated trace; replay itself does not overwrite the source. Overrides are merged into the chosen workflow configuration, while comparison, output, error, cost, and duration describe the new execution.

Machine replay access is write-only

This public surface creates and cancels replays but does not offer a machine GET replay endpoint. Observe progress over authorized realtime replay topics or through the operator observability UI/API rather than inventing a polling URL.

Cancellation is represented as failure

Stored statuses are queued, running, completed, or failed. Cancelling queued/running work returns a replay with status: failed and error_payload.code: cancelled; there is no stored cancelled replay status.

How it works

1. Inspect the source

   Inspect the trace in operator observability, or read it through the machine API with traces:read. Confirm it is replayable and identify its target, workflow version, input, and recorded connector context. Do not replay an external side effect casually.

2. Submit a labelled variant

   POST the source trace_id and a meaningful variant_label; add only intentional prompt, model, raw config, workflow-version, or source-context overrides.

3. Observe or cancel

   Save the replay and generated-trace IDs from HTTP 201. Subscribe to replay events or use operator observability; cancel only while queued/running and treat the returned failed/cancelled error payload as terminal.

Examples

These examples are illustrative. Replace the sample values with your own. Keep credentials in environment variables or a secret manager, never in client-side code.

export AGENTOPS_BASE_URL="https://robotscenter.net"
export AGENT_TOKEN="machine_token_with_replays_write"
export SOURCE_TRACE_ID="6646e3ff-8f2f-4204-ad5c-f4ebc1830f9e"

jq -n --arg trace "$SOURCE_TRACE_ID" \
  '{trace_id: $trace, variant_label: "concise-answer-v2", model_override: "gpt-4.1", prompt_override: "Answer accurately in no more than three sentences."}' |
  curl --fail-with-body --silent --show-error \
    -X POST -H 'content-type: application/json' \
    -H "Authorization: Bearer $AGENT_TOKEN" \
    --data-binary @- "$AGENTOPS_BASE_URL/api/v1/replays" | jq .

Troubleshooting

Creation returns 404

The source trace is absent from the credential's workspace. Trace IDs never cross workspace boundaries, even when the caller knows a valid UUID from elsewhere.

A replay cannot select a target

Supply workflow_target_id when the source trace did not record one. The target and any workflow version must belong to the same workspace.

Cancel returns cannot_cancel

Only queued or running replays can be cancelled. Completed, failed, and already-cancelled-as-failed records are terminal.

No machine polling route exists

Use operator observability, or mint a socket token from a credential carrying both sockets:connect and events:read before joining replay:{replay_id}. replays:write alone cannot join that topic. Do not poll a guessed GET /api/v1/replays/:id route.

Endpoint reference

Ready to integrate? Open an endpoint for its required permissions, request fields, response format, and status codes. The examples above explain the workflow; these details define each individual request.

{
  "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.0400",
  "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"
}

{
  "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.0400",
  "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"
}