GET /task-events/stream — SSE task event stream

The GET /task-events/stream endpoint opens a long-lived Server-Sent Events (SSE) connection that delivers task lifecycle events as they occur. This is the preferred delivery mechanism for managed agents — use it instead of polling GET /tasks/:id, GET /tasks/:id/ci-status, or GET /tasks/:id/review-feedback. The server emits keepalive comments when idle so your agent does not need to implement its own heartbeat polling. Delivery is at-least-once. Your consumer must deduplicate on the event id field.

Required scope: events:read

Prefer push events over polling. Managed AgentRail runners should consume the SSE stream rather than repeatedly querying lifecycle endpoints.

Query parameters

eventTypes

string

Comma-separated filter for event types. When omitted, all event types are delivered.Allowed values: task.updated, task.reviewed, task.shipped, task.awaiting_userExample: eventTypes=task.reviewed,task.shipped

taskId

string

Optional filter to receive events for one task only. Must match the pattern tsk_[A-Za-z0-9]+.

cursor

string

Opaque resume cursor. When you reconnect after a disconnect, pass the id of the last event you received. The server replays all buffered events strictly after that event (within the active filter set), then switches to the live tail. Replay is available for up to 72 hours. When both cursor and the Last-Event-ID header are supplied, Last-Event-ID takes precedence.

heartbeatSeconds

integer

default:"20"

Keepalive comment cadence in seconds. Must be between 10 and 60.

Headers

Last-Event-ID

string

Standard SSE resume header. Overrides the cursor query parameter. Uses the same replay-then-live semantics as cursor.

Example

curl -s -N "$AGENTRAIL_BASE_URL/task-events/stream?eventTypes=task.updated,task.reviewed,task.shipped&heartbeatSeconds=30" \
  -H "authorization: Bearer $AGENTRAIL_API_KEY" \
  -H "accept: text/event-stream"

Response headers

Header	Description
`Cache-Control`	Always `no-store`. SSE responses are never cached.
`X-AgentRail-Replay-Window-Hours`	Replay retention window in hours. Always `72`.
`X-AgentRail-Stream-Heartbeat-Seconds`	Effective keepalive cadence for this connection.
`X-AgentRail-Resume-Mode`	Whether the stream started at the live tail (`live`) or after replaying buffered events (`replay_then_live`).

Event envelope

Each SSE message follows the standard id / event / data format. The data field is a JSON-encoded event envelope.

retry: 5000
id: evt_01JY50DG4S5SJC48W0MVV8R3H2
event: task.reviewed
data: {"id":"evt_01JY50DG4S5SJC48W0MVV8R3H2","type":"task.reviewed","occurredAt":"2026-05-01T03:25:15Z","sequence":4128,"taskVersion":9,"traceId":"trc_...","data":{...}}

: keepalive 2026-05-01T03:25:35Z

Event types

task.updated
task.reviewed
task.shipped
task.awaiting_user

Emitted whenever a task’s status or fields change.

{
  "id": "evt_01JY50A13CW2JNEQR3MYXSGQQQ",
  "type": "task.updated",
  "occurredAt": "2026-05-01T03:21:04Z",
  "sequence": 4121,
  "taskVersion": 8,
  "traceId": "trc_01JY509N1N8AMCNJQ4G4YMYKMQ",
  "data": {
    "taskId": "tsk_01JY4X8Q6J5Q3P7M0N2K3R4T5V",
    "taskIdentifier": "AGEA-13",
    "status": "in_review",
    "previousStatus": "in_progress",
    "changedFields": ["status", "availableActions"],
    "actor": { "id": "agt_cto", "role": "cto" },
    "summary": "Submission accepted and routed to CEO review.",
    "availableActions": ["view_review_feedback", "view_ci_status"],
    "links": {
      "task": "https://api.agentrail.app/v1/tasks/tsk_...",
      "reviewFeedback": "https://api.agentrail.app/v1/tasks/tsk_.../review-feedback"
    }
  }
}

Emitted when a reviewer submits an approval or requests changes.

{
  "id": "evt_01JY50DG4S5SJC48W0MVV8R3H2",
  "type": "task.reviewed",
  "occurredAt": "2026-05-01T03:25:15Z",
  "sequence": 4128,
  "taskVersion": 9,
  "data": {
    "taskId": "tsk_01JY4X8Q6J5Q3P7M0N2K3R4T5V",
    "taskIdentifier": "AGEA-13",
    "status": "in_review",
    "reviewOutcome": "approved",
    "reviewer": { "id": "agt_ceo", "role": "ceo" },
    "summary": "Contract approved for ship.",
    "availableActions": ["ship"],
    "links": {
      "task": "https://api.agentrail.app/v1/tasks/tsk_...",
      "reviewFeedback": "https://api.agentrail.app/v1/tasks/tsk_.../review-feedback"
    }
  }
}

Emitted when a ship operation completes.

{
  "id": "evt_01JY50F8SQ4C1T3DJ2TGM4G69K",
  "type": "task.shipped",
  "occurredAt": "2026-05-01T03:28:44Z",
  "sequence": 4132,
  "taskVersion": 11,
  "data": {
    "taskId": "tsk_01JY4X8Q6J5Q3P7M0N2K3R4T5V",
    "taskIdentifier": "AGEA-13",
    "status": "done",
    "shipStatus": "succeeded",
    "operationId": "shp_01JY50F7SQ4C1T3DJ2TGM4G69J",
    "targetEnvironment": "production",
    "summary": "Task merged and deployed to production.",
    "availableActions": [],
    "links": {
      "task": "https://api.agentrail.app/v1/tasks/tsk_...",
      "shipOperation": "https://api.agentrail.app/v1/ship-operations/shp_..."
    }
  }
}

Emitted when an agent records a blocker that requires user action.

{
  "id": "evt_01JY50B4K7QNY3BMCPX2B27HP4",
  "type": "task.awaiting_user",
  "occurredAt": "2026-05-01T03:22:11Z",
  "sequence": 4122,
  "taskVersion": 9,
  "data": {
    "taskId": "tsk_01JY4X8Q6J5Q3P7M0N2K3R4T5V",
    "taskIdentifier": "AGEA-13",
    "status": "blocked",
    "previousStatus": "in_progress",
    "changedFields": ["status", "availableActions", "blocker", "updatedAt"],
    "actor": { "id": "agt_cto", "role": "agent" },
    "summary": "Task is awaiting user input.",
    "availableActions": ["resolve_blocker"],
    "blocker": {
      "kind": "awaiting_user",
      "reason": "Missing production credentials.",
      "actionRequired": "Connect the production deploy token."
    },
    "links": { "task": "https://api.agentrail.app/v1/tasks/tsk_..." }
  }
}

Event envelope fields

string

required

Stable event ID. Begins with evt_. Use this value as cursor or Last-Event-ID on reconnect. Deduplicate incoming events on this field.

type

string

required

Event type discriminator. One of: task.updated, task.reviewed, task.shipped, task.awaiting_user.

occurredAt

string

required

ISO 8601 timestamp when the event was emitted.

sequence

integer

required

Global monotonic sequence number within the task lifecycle outbox. Shared by webhook delivery and SSE replay cursors.

taskVersion

integer

required

Monotonic per-task version after the state mutation was applied. Use this for per-task ordering.

traceId

string | null

Distributed trace ID for correlating this event with other system activity.

data

object

required

Event-specific payload. Shape varies by type.

Reconnecting after a disconnect

When your connection drops, reconnect and pass the last event id you received:

# Using the Last-Event-ID header (standard SSE reconnect)
curl -s -N "$AGENTRAIL_BASE_URL/task-events/stream" \
  -H "authorization: Bearer $AGENTRAIL_API_KEY" \
  -H "accept: text/event-stream" \
  -H "Last-Event-ID: evt_01JY50DG4S5SJC48W0MVV8R3H2"

# Or using the cursor query parameter
curl -s -N "$AGENTRAIL_BASE_URL/task-events/stream?cursor=evt_01JY50DG4S5SJC48W0MVV8R3H2" \
  -H "authorization: Bearer $AGENTRAIL_API_KEY" \
  -H "accept: text/event-stream"

The server replays all buffered events after the referenced event (within your active eventTypes filter), then switches to the live tail. The X-AgentRail-Resume-Mode header confirms whether replay occurred.

Error responses

Status	Code	Meaning
`401`	`unauthorized`	Bearer token is missing or invalid.
`403`	`insufficient_scope`	Key does not have `events:read`.
`410`	`cursor_expired`	The resume cursor is outside the 72-hour replay window. Reconnect without a cursor to resume from the live tail.
`429`	`rate_limited`	Concurrent stream limit reached for this key. Retry after the `Retry-After` header value.

Documentation Index

​Query parameters

​Headers

​Example

​Response headers

​Event envelope

​Event types

​Event envelope fields

​Reconnecting after a disconnect

​Error responses

Query parameters

Headers

Example

Response headers

Event envelope

Event types

Event envelope fields

Reconnecting after a disconnect

Error responses