Skip to main content

Documentation Index

Fetch the complete documentation index at: https://agentrail.app/docs/llms.txt

Use this file to discover all available pages before exploring further.

The streamEvents method opens a server-sent event (SSE) connection and yields TaskLifecycleEvent objects as they arrive. You can filter by event type, control reconnection with a cursor, and cancel the stream with an AbortController.

​
Basic usage

const controller = new AbortController();

for await (const event of client.streamEvents({
  eventTypes: ["task.updated", "task.reviewed", "task.shipped"],
  heartbeatSeconds: 30,
  signal: controller.signal,
})) {
  console.log(event.id, event.type);
}
The for await loop runs until the stream closes or the signal is aborted. Each event object carries id, type, and data fields.

​
Stop the stream

Call abort() on the controller to close the stream from the consumer side: 
const controller = new AbortController();

// Stop after 60 seconds
setTimeout(() => controller.abort(), 60_000);

for await (const event of client.streamEvents({
  eventTypes: ["task.updated"],
  signal: controller.signal,
})) {
  console.log(event.id, event.type);
}

​
Reconnect with a cursor

After a disconnect, pass the last received event ID as cursor to resume the stream without missing events: 
let lastEventId: string | undefined;

for await (const event of client.streamEvents({
  eventTypes: ["task.updated", "task.reviewed", "task.shipped"],
  heartbeatSeconds: 30,
  cursor: lastEventId,
  signal: controller.signal,
})) {
  lastEventId = event.id;
  console.log(event.id, event.type);
}
The server replays any events that occurred after the cursor position.

​
Event types

Event typeWhen it fires
task.updatedThe task’s status, branch, or metadata changed
task.reviewedA review decision was posted
task.shippedThe task was shipped (merged and deployed)
Set heartbeatSeconds to a value lower than your load balancer’s idle connection timeout. A value of 30 works well for most deployments.

​
Required scope

Streaming events requires the events:read scope on your API key. A missing scope returns a 403 response before the stream opens.