# Watching a run

> Resume a run's event stream from the last event you saw, without replaying or skipping.

Section: Synapse and Locus. Web page: https://docs.katara.com/products/run-events/

A run reports what it is doing as a sequence of events. Each one carries a
number, and that number is where you resume from. It is a counter, not a clock:
two changes in the same millisecond are two events, and nothing you read depends
on our clock agreeing with yours.

```
GET /katara/v1/orgs/{org_id}/environments/{environment_id}/runs/{id}/events
```

Send `Accept: text/event-stream` and you get server-sent events whose `id` is
the sequence. A browser `EventSource` sends `Last-Event-ID` when it reconnects,
so resumption costs you nothing to write. Without that header the same events
come back as one page of JSON, which is what a script wants.

```ts
const events = new EventSource(url, { withCredentials: true });
events.addEventListener("run.completed", event => {
  const { sequence, snapshot } = JSON.parse(event.data);
  console.log(sequence, snapshot?.steps);
});
```

For a client that keeps its own position, `from` is the same resumption point:

```ts
const page = await client.runEvents(scope, runId, lastSequence);
for (const event of page.data) apply(event);
```

## Where you are

`next_sequence` is the number to resume from next time. Passing zero, or leaving
`from` out, says you hold nothing yet; you are given what is still kept rather
than being told anything is missing.

A finished run ends the stream instead of holding the connection open. A stream
that has been open a long time also ends on its own; reconnect with the last id
you saw and you lose nothing.

## When events are gone

Once a run has finished, the steps along the way are eventually dropped. What
happened to the run is kept. `retained_from` is the earliest sequence still
held, and resuming from below it answers **410** with `stream_gone` rather than
handing you the next thing that still exists, because a gap you could not see is
worse than an error you can.

On a 410, read the run itself to see where it got to and carry on from there.

## What you need

Reading events needs the same permission as reading the run. That permission is
rechecked on every page, so access removed while a stream is open ends it.