Documentation menu
Agent Runs

Stream live run telemetry

GET /api/v1/agent-runs/{agentRunId}/stream

Stream live runtime telemetry for an agent run via Server-Sent Events (SSE).

  • Runtime PerstackEvent objects are relayed as message events.
  • ping events are transport keepalives only.
  • Lifecycle state is not relayed while the run is live. Use GET /agent-runs/:id for current state, /transitions for lifecycle history, and checkpoints for durable runtime history/replay.
  • The stream is bound to the run attempt it attached to. It closes when that attempt's runtime telemetry ends, or within about two seconds after the run leaves its live state (running / canceling) or the attached attempt ends, whether or not a terminal runtime event was relayed.
  • When the stream closes because the run left its live state for the attached attempt, its last event is an end event whose data is { type: "end", agentRunId, state, timestamp } with the run state observed at close (for example failed, completed, canceled, expired, or an awaiting state). A stream that closes without an end event (telemetry lost while the run is still live, or authorization loss) carries no outcome: read GET /agent-runs/:id and re-attach only when that state is live again.
  • The route performs auth/resource/state/runner-attach preflight before the SSE body starts. Non-live states return HTTP status: 409 when no live runtime stream exists. Startup returns 409 with details.conflictReason=run_not_ready, currentState, retryable=true and Retry-After; read the Run state before attaching again. Paused or settled Runs return run_not_streamable with retryable=false. Runner attachment that is temporarily unavailable for a live Run returns 503 + Retry-After.

Authentication

  • Requires a valid session or API key in the Authorization header

Parameters

path

NameTypeRequiredDescription
agentRunIdstringrequiredIdentifies the agent run whose state or history is addressed. Applies to Stream live run telemetry.

Responses

StatusDescriptionBody
200SSE stream (text/event-stream)text/event-stream — string
400The request is malformed or cannot be processed.application/json — PublicApiError — error: object (required)
401Authentication failed. The Authorization header is missing, or the credential is invalid or expired.application/json — PublicApiError — error: object (required)
403Access denied. The authenticated user does not have permission to perform this action.application/json — PublicApiError — error: object (required)
404Resource not found.application/json — PublicApiError — error: object (required)
409Request conflicts with current state of the resource, including safe deployment conflict classifications.application/json — PublicApiError — error: object (required)
422Request validation failed. Check the request body, query parameters, or path parameters.application/json — PublicApiError — error: object (required)
429Too many requests.application/json — PublicApiError — error: object (required)
500The server could not complete the request.application/json — PublicApiError — error: object (required)
503Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff.application/json — PublicApiError — error: object (required)