> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clickbase.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Session replay

> List, play back, and delete session replays — recorded rrweb event streams of a visitor's session — for one of the current team's sites.

List, play back, and delete session replays — recorded rrweb event streams of a visitor's session — for one of the current team's sites. A site is addressed by `{siteKey}` (UUID or domain). All endpoints require `Authorization: Bearer {token}`. See [Conventions](/api/conventions) for the base URL, headers, and date-range conventions shared by every endpoint.

A session only appears in this API once it has a full rrweb snapshot **and** at least 2 recorded events — a single-event session has nothing worth playing back.

### List replays

```http theme={null}
GET /api/sites/{siteKey}/replays
```

**Paginated** — the standard `data`/`meta`/`links` envelope (see [Response envelope](/api/conventions#response-envelope)), at a **fixed internal page size of 20**. Advance with `?page=`; there is no `per_page` parameter for this endpoint.

**Path parameters**

| Parameter | Type   | Required | Description          |
| --------- | ------ | -------- | -------------------- |
| `siteKey` | string | Yes      | Site UUID or domain. |

**Query parameters**

| Parameter      | Type   | Required | Description                                                                           |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------- |
| `range`        | string | No       | Preset date range (see [Date ranges](/api/conventions#date-ranges)). Default `today`. |
| `from`         | string | No       | Custom range start, `Y-m-d`. Requires `to`.                                           |
| `to`           | string | No       | Custom range end, `Y-m-d`. Requires `from`.                                           |
| `min_duration` | int    | No       | Minimum session duration in seconds, 0–86400. Default 30.                             |
| `page`         | int    | No       | Page number (fixed 20-per-page). Default 1.                                           |

Only a subset of the shared [dashboard filters](/api/conventions#filters) apply to this list, because replay metadata only carries a session's *last-seen* dimensions: `path` (substring match on the recorded page URL), `country`, `browser`, `os`, and `device`/`size`. Any other filter key (e.g. `referrer`, `goal`) is silently ignored here.

**Response** — each item in `data`:

| Field                         | Type              | Description                                                        |
| ----------------------------- | ----------------- | ------------------------------------------------------------------ |
| `session_id`                  | string (uuid)     | Session id.                                                        |
| `visitor_id`                  | string (uuid)     | Visitor id.                                                        |
| `identified_user_id`          | string            | Identified user id, or `""` when the visitor was never identified. |
| `display_name`                | string            | Human-readable label for the session's visitor/user.               |
| `page_url`                    | string            | The page the recording started on.                                 |
| `country` / `region` / `city` | string            | Location.                                                          |
| `browser` / `browser_version` | string            | Browser and version.                                               |
| `os` / `os_version`           | string            | Operating system and version.                                      |
| `device`                      | string            | Device kind.                                                       |
| `language`                    | string            | Browser language.                                                  |
| `event_count`                 | int               | Number of recorded rrweb events.                                   |
| `duration_seconds`            | int               | Session duration, floored to whole seconds.                        |
| `start_time` / `end_time`     | string (ISO 8601) | Recording start/end.                                               |

Status: `200 OK`.

<CodeGroup>
  ```bash title="curl" theme={null}
  curl "https://clickbase.so/api/sites/example.com/replays?min_duration=30" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/json"
  ```

  ```javascript title="JavaScript" theme={null}
  await fetch('https://clickbase.so/api/sites/example.com/replays?min_duration=30', { headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' } })
  ```

  ```python title="Python" theme={null}
  requests.get('https://clickbase.so/api/sites/example.com/replays', params={'min_duration': 30}, headers={'Authorization': f'Bearer {token}', 'Accept':'application/json'})
  ```
</CodeGroup>

### Get a replay

```http theme={null}
GET /api/sites/{siteKey}/replays/{sessionId}
```

Metadata plus the full hydrated rrweb event stream for one session's player.

**Path parameters**

| Parameter   | Type          | Required | Description                                    |
| ----------- | ------------- | -------- | ---------------------------------------------- |
| `siteKey`   | string        | Yes      | Site UUID or domain.                           |
| `sessionId` | string (uuid) | Yes      | Session id. Unknown or non-UUID returns `404`. |

**Response** — a flat object:

| Field      | Type   | Description                                                                                                                                                      |
| ---------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `metadata` | object | Same fields as a list row, plus `hostname`.                                                                                                                      |
| `events`   | array  | Ordered rrweb events: `{ type, timestamp, data }` — `type` is the rrweb event type (0–6), `timestamp` is a millisecond epoch, `data` is the rrweb event payload. |

Status: `200 OK`. A foreign/unknown `sessionId` returns `404 Not Found`.

<CodeGroup>
  ```bash title="curl" theme={null}
  curl "https://clickbase.so/api/sites/example.com/replays/{sessionId}" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/json"
  ```

  ```javascript title="JavaScript" theme={null}
  await fetch(`https://clickbase.so/api/sites/example.com/replays/${sessionId}`, { headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' } })
  ```

  ```python title="Python" theme={null}
  requests.get(f'https://clickbase.so/api/sites/example.com/replays/{session_id}', headers={'Authorization': f'Bearer {token}', 'Accept':'application/json'})
  ```
</CodeGroup>

### Delete a replay

```http theme={null}
DELETE /api/sites/{siteKey}/replays/{sessionId}
```

Permanently delete a session replay — its recorded event blobs and all ClickHouse rows. Cannot be undone; there is no soft-delete or TTL for replays.

**Path parameters**

| Parameter   | Type          | Required | Description                                    |
| ----------- | ------------- | -------- | ---------------------------------------------- |
| `siteKey`   | string        | Yes      | Site UUID or domain.                           |
| `sessionId` | string (uuid) | Yes      | Session id. Unknown or non-UUID returns `404`. |

Status: `204 No Content`. A foreign/unknown `sessionId` returns `404 Not Found`.

<CodeGroup>
  ```bash title="curl" theme={null}
  curl -X DELETE "https://clickbase.so/api/sites/example.com/replays/{sessionId}" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/json"
  ```

  ```javascript title="JavaScript" theme={null}
  await fetch(`https://clickbase.so/api/sites/example.com/replays/${sessionId}`, { method: 'DELETE', headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' } })
  ```

  ```python title="Python" theme={null}
  requests.delete(f'https://clickbase.so/api/sites/example.com/replays/{session_id}', headers={'Authorization': f'Bearer {token}', 'Accept':'application/json'})
  ```
</CodeGroup>

### Enable session replay

```http theme={null}
POST /api/sites/{siteKey}/replays/enable
```

Route name: `api.sites.replays.enable`. Turns on `track_session_replay` for the site so the tracker starts recording new sessions. This is the only replay-specific enable toggle; see [Tracking configuration](/api/tracking-config) for the Web Vitals and error-tracking equivalents and for the response fields shared by all three.

**Response** — the updated site (`SiteResource`, same shape as [Sites](/api/sites#response-fields), including `track_session_replay: true`). Status: `200 OK`.

<CodeGroup>
  ```bash title="curl" theme={null}
  curl -X POST "https://clickbase.so/api/sites/example.com/replays/enable" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/json"
  ```

  ```javascript title="JavaScript" theme={null}
  await fetch('https://clickbase.so/api/sites/example.com/replays/enable', { method: 'POST', headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' } })
  ```

  ```python title="Python" theme={null}
  requests.post('https://clickbase.so/api/sites/example.com/replays/enable', headers={'Authorization': f'Bearer {token}', 'Accept':'application/json'})
  ```
</CodeGroup>