> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://platform.bctrl.ai/llms.txt.
> For full documentation content, see https://platform.bctrl.ai/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://platform.bctrl.ai/_mcp/server.

# Runs

> The durable record of a runtime's lifecycle - events, activity, live view, recording, and files.

A **run** is the durable record of a runtime's lifecycle, from start to stop. Every start opens a run that records structured events, an activity timeline, a live view you can watch or take over, a replayable recording, and any files produced. Use it to see what an agent did while it ran and to replay it afterward.

## Read a run

```ts
const run = await bctrl.runs.get(runId);

const { data } = await bctrl.runs.list({ spaceId: space.id, status: "completed" });

for await (const r of bctrl.runs.iter({ runtimeId: runtime.id })) {
  console.log(r.id, r.status);
}
```

## Events and activity

Events are the structured timeline of what happened in the run. List them, or stream them live:

```ts
const events = await bctrl.runs.events.list(runId);

for await (const event of bctrl.runs.events.iter(runId)) {
  console.log(event.type, event.time);
}
```

`activity` is the higher-level view over the same run:

```ts
const activity = await bctrl.runs.activity.list(runId);
```

Both expose a `streamUrl(runId)` for server-sent events. See [Streaming](/sdk/essentials).

## Live view

Mint a short-lived viewer URL to watch a run, optionally with human takeover:

```ts
const live = await bctrl.runs.live(runId, { control: "none" });
console.log(live.url, live.expiresAt);
```

Set `control: "input"` to let a human take over the browser through the iframe.

## Recording

Once a run ends, mint a recording viewer to replay it:

```ts
const recording = await bctrl.runs.recording(runId);
console.log(recording.url, recording.durationMs);
```

## Files

List the files a run produced, or export them as a downloadable archive:

```ts
const files = await bctrl.runs.files.list(runId);
const archive = await bctrl.runs.files.export(runId, {
  name: "session-files",
  type: ["download"],
});
```

## Next

* [Events & Activity](/sdk/events) - the structured timeline in depth
* [Invocations](/sdk/invocations) - the hosted work recorded in a run
* [Streaming](/sdk/essentials) - subscribe to run events over SSE