Skip to main content
The events endpoint provides a real-time Server-Sent Events (SSE) stream of everything happening in your project. Use it to build dashboards, trigger webhooks, or monitor agent activity.

​
Authentication

​
Authorization
string
required
Bearer token using your project API key. Authorization: Bearer sk_live_...

​
Stream events

​
GET /events
Opens a persistent SSE connection. Events are pushed to the client as they occur.

​
Query parameters

​
filter
string
Comma-separated list of event patterns to subscribe to. Supports wildcards with *. If omitted, all events are streamed.Examples: task:*, mission:created,mission:completed, agent:*,task:transition

​
Headers

​
Last-Event-ID
string
The ID of the last event received. When provided, the server replays all events after this ID before switching to live streaming. Use this for reconnection without missing events.

​
Event types

EventFired when
task:createdA new task is created
task:transitionA task changes status (e.g. pending to active)
task:completedA task finishes successfully
mission:executedA mission begins execution
mission:completedA mission finishes (success or failure)
agent:spawnedAn agent is activated for a task
agent:completedAn agent finishes its work on a task
schedule:triggeredA scheduled mission fires
assessment:completedA task assessment finishes
approval:requestedA human approval gate is triggered

​
SSE wire format

Each event follows the standard SSE format: 
event: task:transition
data: {"taskId":"tsk_abc123","from":"pending","to":"active","agentName":"backend-dev","timestamp":"2026-03-16T14:30:00Z"}
id: evt_00042
FieldDescription
eventThe event type (e.g. task:transition)
dataJSON payload with event-specific fields
idMonotonically increasing event ID for replay
Each event is terminated by a blank line (\n\n). This is part of the SSE specification and is how the client knows an event is complete.

​
Examples

​
curl

Stream all events: 
curl -N https://api.polpo.sh/v1/events \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "Accept: text/event-stream"
Stream only task events: 
curl -N "https://api.polpo.sh/v1/events?filter=task:*" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "Accept: text/event-stream"
Reconnect from a specific event: 
curl -N https://api.polpo.sh/v1/events \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "Accept: text/event-stream" \
  -H "Last-Event-ID: evt_00042"

​
JavaScript (EventSource)

const eventSource = new EventSource(
  "https://api.polpo.sh/v1/events?filter=task:*,mission:*",
  {
    headers: { Authorization: "Bearer sk_live_abc123" },
  }
);

eventSource.addEventListener("task:transition", (e) => {
  const data = JSON.parse(e.data);
  console.log(`Task ${data.taskId} moved to ${data.to}`);
});

eventSource.addEventListener("mission:completed", (e) => {
  const data = JSON.parse(e.data);
  console.log(`Mission ${data.missionId} finished: ${data.status}`);
});

eventSource.onerror = (e) => {
  console.error("SSE connection lost, reconnecting...");
};

​
Reconnection

The server stores a sliding window of recent events. When you reconnect with Last-Event-ID: evt_00042, the server replays all events with an ID greater than evt_00042 before switching to live mode. This guarantees at-least-once delivery as long as the event is still within the replay window.
The EventSource API in browsers automatically reconnects on connection loss and sends the last received event ID. If you are using curl or a custom client, you must track the last id field yourself and include it as the Last-Event-ID header on reconnection.
The replay window is finite. If a client disconnects for an extended period, some events may fall outside the window and will not be replayed. For durable event consumption, use the events endpoint in combination with polling the relevant resource endpoints (e.g. GET /tasks) to reconcile state.

​
Filter patterns

Filters use a simple pattern syntax:
PatternMatches
task:*All task events (task:created, task:transition, task:completed)
mission:completedOnly mission:completed events
*All events (same as omitting the filter)
task:*,agent:*All task and agent events
approval:requestedOnly approval request events