# Event stream

> Follow every event of a project live over Server-Sent Events, resume after a disconnect, filter by type, and list recent events over HTTP.

Every change in a project is recorded as an event: the same events [webhooks](/docs/webhooks.md) send. Webhooks push them to a public URL. The event stream lets a program that runs all the time, such as an agent that waits for new uploads or a search indexer, read them live over one HTTP connection, with no public URL of its own.

The stream is part of Pro and up. The list of recent events works on every plan.

## Open the stream

```bash
curl -N "https://api.galerne.cloud/p/acme/v1/events/stream?types=doc.published,media.*" \
  -H "Authorization: Bearer gal_…"
```

The answer is a [Server-Sent Events](https://html.spec.whatwg.org/multipage/server-sent-events.html) stream. Each message carries the event type as `event`, the event sequence number as `id`, and the event as JSON in `data`:

```text
event: doc.published
id: 4182
data: {"seq":4182,"id":"evt_8KfQ2x…","type":"doc.published","branch":"main","doc_id":"harbours","doc_type":"post","actor":"human:acc_…","actor_name":"Marie","data":{},"created_at":"2026-10-16T09:22:41.000Z"}
```

| Field | What it holds |
|---|---|
| `seq` | The position of the event in the project, growing by one or more each time |
| `id` | The event id, the same as the `id` of the webhook payload |
| `type` | The event type; the [webhooks page](/docs/webhooks.md#events) lists all 20 |
| `branch`, `doc_id`, `doc_type` | Where it happened, when it concerns a branch or a document |
| `actor`, `actor_name` | Who did it, as `<kind>:<id>` (`human`, `agent`, `token` or `system`) and a display name |
| `data` | Details that depend on the event |
| `created_at` | ISO 8601 time |

When nothing happens for 25 seconds, the server sends an `event: ping` with empty data, so proxies keep the connection open.

## Filter

`types` takes a comma-separated list of event types. A type ending in `.*` matches every event that starts with the prefix: `review.*` matches `review.requested`, `review.approved` and `review.changes_requested`. Without `types`, the stream sends everything.

## Resume

Without a position, the stream starts with the events that happen after you connect. To pick up where you stopped, send the last `id` you received:

- in the `Last-Event-ID` header, which browsers' `EventSource` sends on its own when it reconnects;
- or as `?since=<seq>`.

The stream then replays every event after that one, in order, and continues live. Events are kept 90 days.

## In a browser or in Node.js

`EventSource` cannot send an `Authorization` header, so read the stream with `fetch` on a server or in a worker:

```ts
const response = await fetch('https://api.galerne.cloud/p/acme/v1/events/stream?types=media.uploaded', {
  headers: { Authorization: `Bearer ${process.env.GALERNE_TOKEN}` },
})
const reader = response.body!.pipeThrough(new TextDecoderStream()).getReader()
let buffer = ''
while (true) {
  const { value, done } = await reader.read()
  if (done) break
  buffer += value
  const messages = buffer.split('\n\n')
  buffer = messages.pop() ?? ''
  for (const message of messages) {
    const data = message.split('\n').find((line) => line.startsWith('data: '))?.slice(6)
    if (!data) continue
    const event = JSON.parse(data)
    console.log(event.type, event.doc_id)
  }
}
```

## Access and limits

- The token needs the `read` scope. The stream sends every event of the project, whatever the token's type or branch rules.
- A token may hold 5 open streams at once, and a project 50. Over that, the API answers `429` with code `rate_limited`.
- On the Free plan, the stream answers `402` with code `feature`.

## Recent events

`GET /p/<project>/v1/events` lists recent events, newest first, on every plan. It needs the `read` scope.

```bash
curl "https://api.galerne.cloud/p/acme/v1/events?limit=50" -H "Authorization: Bearer gal_…"
```

```json
{ "events": [{ "seq": 4182, "id": "evt_8KfQ2x…", "type": "doc.published", "branch": "main", "doc_id": "harbours", "doc_type": "post", "actor": "human:acc_…", "actor_name": "Marie", "data": {}, "created_at": "2026-10-16T09:22:41.000Z" }] }
```

`limit` goes up to 500, 50 by default. To page back, pass the smallest `seq` you got as `before`.
