# Live events

`met.events` is the feed of what happens in your workspace: runs that finish, messages arriving through a channel, contacts being created. You can read it live over **Server-Sent Events (SSE)** or query the recent history. Requires the `events:read` scope.

## Listen live with `stream()`

`met.events.stream()` opens an **ephemeral** SSE subscription that emits each event as soon as it happens. It is the same source `met listen` uses in the CLI: ideal for the dev loop and for real time without standing up an endpoint.

```ts
const met = new Met(key, { workspaceId });

for await (const ev of met.events.stream()) {
  console.log(ev.type, ev.data);
}
```

Each `ev` is an `{ id, type, created, livemode, data }` — the same types as the outbound webhooks catalog.

### Filter by type

Pass `types` to receive only what you care about:

```ts
for await (const ev of met.events.stream({ types: ['run.completed', 'contact.message.received'] })) {
  if (ev.type === 'run.completed') console.log('run done:', ev.data);
}
```

### Stop the stream

Break out of the `for await` (with `break`), or pass an `AbortSignal` to close it from the outside:

```ts
const ac = new AbortController();
setTimeout(() => ac.abort(), 30_000);   // cuts off after 30s

for await (const ev of met.events.stream({ signal: ac.signal })) {
  console.log(ev.type);
}
```

Some useful types from the catalog: `run.completed`, `run.failed`, `contact.message.received`, `contact.created`, `task.completed`, `conversation.handoff`.

> **`stream()` vs. outbound webhooks.** `met.events.stream` is ephemeral: it does not retry, and events only reach you while your process is connected. It is meant for development and real time. For **guaranteed cross-instance delivery** — the event arrives even if your service is down, and gets retried — set up a persistent webhook. See [Webhooks](webhooks.html).

## Query the history

When you don't need real time, read what already happened:

```ts
const events   = await met.events.list();               // latest events (default 50)
const activity = await met.events.activity();           // workspace activity (default 50)
const ofItem   = await met.events.itemActivity(1234);   // activity of a single item
```

Both `list()` and `activity()` accept `{ limit }` to adjust how many records to bring back.