> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polpo.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> Stream live project events over SSE

`GET /v1/events` opens a live Server-Sent Events stream for a project.

## Connect

```bash theme={null}
curl -N https://{project}.polpo.cloud/v1/events \
  -H "Authorization: Bearer $POLPO_API_KEY" \
  -H "Accept: text/event-stream"
```

Use `filter` to select comma-separated event names or prefixes supported by the runtime:

```bash theme={null}
curl -N 'https://{project}.polpo.cloud/v1/events?filter=task:,completion:' \
  -H "Authorization: Bearer $POLPO_API_KEY"
```

Events use standard SSE framing:

```text theme={null}
id: 42
event: task:transition
data: {"taskId":"task_123","from":"in_progress","to":"done"}
```

## Delivery semantics

The Cloud bridge forwards live events and does not maintain a replay buffer. `Last-Event-ID` is not replayed, IDs can reset when the project runtime restarts, and reconnecting clients must reconcile state through resource endpoints such as `GET /v1/tasks`.

Native browser `EventSource` cannot set the required authorization header. Do not put a project API key in the URL: the Cloud middleware does not authenticate an `apiKey` query parameter. Connect from a server-side EventSource implementation that supports headers, or expose an authenticated application-owned proxy to the browser.

```typescript theme={null}
import EventSource from "eventsource";

const events = new EventSource("https://{project}.polpo.cloud/v1/events", {
  fetch: (input, init) => fetch(input, {
    ...init,
    headers: { ...init?.headers, Authorization: `Bearer ${process.env.POLPO_API_KEY}` },
  }),
});

events.addEventListener("task:transition", (event) => {
  console.log(JSON.parse(event.data));
});
```

See the [event reference](/developers/reference/events) for runtime event names. The smaller webhook catalog is available at `GET https://api.polpo.sh/v1/events/catalog`.