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
messageevents. pingevents are transport keepalives only.- Lifecycle state is not relayed while the run is live. Use
GET /agent-runs/:idfor current state,/transitionsfor 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
endevent whose data is{ type: "end", agentRunId, state, timestamp }with the run state observed at close (for examplefailed,completed,canceled,expired, or an awaiting state). A stream that closes without anendevent (telemetry lost while the run is still live, or authorization loss) carries no outcome: readGET /agent-runs/:idand 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:
409when no live runtime stream exists. Startup returns409withdetails.conflictReason=run_not_ready,currentState,retryable=trueandRetry-After; read the Run state before attaching again. Paused or settled Runs returnrun_not_streamablewithretryable=false. Runner attachment that is temporarily unavailable for a live Run returns503 + Retry-After.
Authentication
- Requires a valid session or API key in the Authorization header
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
agentRunId | string | required | Identifies the agent run whose state or history is addressed. Applies to Stream live run telemetry. |
Responses
| Status | Description | Body |
|---|---|---|
200 | SSE stream (text/event-stream) | text/event-stream — string |
400 | The request is malformed or cannot be processed. | application/json — PublicApiError — error: object (required) |
401 | Authentication failed. The Authorization header is missing, or the credential is invalid or expired. | application/json — PublicApiError — error: object (required) |
403 | Access denied. The authenticated user does not have permission to perform this action. | application/json — PublicApiError — error: object (required) |
404 | Resource not found. | application/json — PublicApiError — error: object (required) |
409 | Request conflicts with current state of the resource, including safe deployment conflict classifications. | application/json — PublicApiError — error: object (required) |
422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json — PublicApiError — error: object (required) |
429 | Too many requests. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |