***

title: Recording
description: Embed a playback recording of a browser runtime session.
---------------------------------------------------------------------

Recordings capture everything that happened in a browser runtime — every page navigation, tab switch, and visual frame. Embed the recording player to replay sessions after they complete.

Access via `runtime.recording()`.

## Getting the embed URL

```ts
const { iframeUrl } = await runtime.recording();
```

The returned `iframeUrl` is a fully authenticated, time-limited URL for the recording player.

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

## Response

```ts
const { iframeUrl, token, expiresAt, status, durationMs, tabIds } =
  await runtime.recording();
```

| Field        | Type       | Description                                           |
| ------------ | ---------- | ----------------------------------------------------- |
| `iframeUrl`  | `string`   | Authenticated URL for the recording player            |
| `token`      | `string`   | Embed token                                           |
| `expiresAt`  | `string`   | Token expiry (ISO 8601)                               |
| `status`     | `string`   | Recording status — `encoding`, `ready`, `expired`     |
| `durationMs` | `number`   | Total recording duration in milliseconds (when ready) |
| `tabIds`     | `string[]` | List of tab IDs captured in the recording             |

## Recording status

| Status     | Description                                                                                        |
| ---------- | -------------------------------------------------------------------------------------------------- |
| `encoding` | The recording is still being processed. The player will show a loading state and poll for updates. |
| `ready`    | The recording is ready to play.                                                                    |
| `expired`  | The recording has been deleted after the retention period.                                         |

Recordings are available while the runtime is still running (for live sessions) and after it stops. Encoding starts automatically when the runtime stops.

## Player features

The recording player includes:

* **Tab strip** — Switch between tabs that were open during the session
* **Timeline scrubber** — Seek to any point in the recording
* **Play/pause** — Standard playback controls
* **Speed control** — 0.5x, 1x, 1.5x, 2x playback speed
* **URL bar** — Shows which page was active at the current playback time
* **Navigation buttons** — Displays the navigation state at each point in time

## Listening for playback events

The recording iframe posts messages to the parent window as playback progresses:

```ts
window.addEventListener("message", (event) => {
  if (event.data?.type === "bctrl:recording-time") {
    console.log("Current time:", event.data.timeMs);
  }
});
```

## Retention

Recordings are retained for **7 days** after the runtime stops. After that, the recording embed returns an expired state.

## HTTP equivalent

```
POST /v1/workspaces/{workspaceId}/runtimes/{alias}/embed/recording
```

Response:

```json
{
  "iframeUrl": "https://...",
  "token": "eyJ...",
  "expiresAt": "2025-01-15T12:00:00Z",
  "status": "ready",
  "durationMs": 45200,
  "tabIds": ["tab_1", "tab_2"]
}
```