> 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.

# Recording

> Embed a playback recording of a completed or in-progress run.

Recordings capture the browser session for a run. Use recording viewers to replay a run after it completes, or to watch recording segments as they become available.

Get the run from the runtime, then create the recording viewer from the run.

```ts
const run = await runtime.currentRun();

const { iframeUrl, status } = await run.recording();
```

```html
<iframe src={iframeUrl} style="width: 100%; height: 600px; border: none;" />
```

<Callout intent="info" title="Viewer URLs are opaque">
  The URL is backed by a short-lived server-side lease. Do not parse it, build sub-URLs from it, or store it long-term. When `expiresAt` passes, create a new viewer URL.
</Callout>

## Options

```ts
const { iframeUrl, activityStreamUrl, status, durationMs, expiresAt } =
  await run.recording({
    components: ["activity"],
  });
```

| Parameter          | Type                | Required | Description                                                                 |
| ------------------ | ------------------- | -------- | --------------------------------------------------------------------------- |
| `components`       | `Array<"activity">` | No       | Request viewer add-ons. Pass `["activity"]` to receive `activityStreamUrl`. |
| `expiresInSeconds` | `number`            | No       | Lease lifetime override. Default is one hour; max is 24 hours.              |

## Recording status

| Status          | Description                                                                     |
| --------------- | ------------------------------------------------------------------------------- |
| `not_available` | The run produced no recording, or the recording window expired.                 |
| `preparing`     | Encoding has not started yet.                                                   |
| `processing`    | Encoding is in flight. The player can show segments that are already available. |
| `ready`         | The recording is available for playback.                                        |
| `failed`        | Encoding failed permanently.                                                    |

## Retention

Recordings are retained for 7 days after the run stops.

## HTTP equivalent

```http
POST /v1/runs/{runId}/recording
```

## Related

* [Runs](/sdk/core-concepts/runs)
* [Live View](/sdk/observability/live-view)
* [Run Artifacts](/sdk/observability/run-artifacts)