REST API

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. A site is addressed by {siteKey} (UUID or domain). All endpoints require Authorization: Bearer {token}. See 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

GET /api/sites/{siteKey}/replays

Paginated — the standard data/meta/links envelope (see 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). 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 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.

curl "https://clickbase.so/api/sites/example.com/replays?min_duration=30" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

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

requests.get('https://clickbase.so/api/sites/example.com/replays', params={'min_duration': 30}, headers={'Authorization': f'Bearer {token}', 'Accept':'application/json'})

Get a replay

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.

curl "https://clickbase.so/api/sites/example.com/replays/{sessionId}" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

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

requests.get(f'https://clickbase.so/api/sites/example.com/replays/{session_id}', headers={'Authorization': f'Bearer {token}', 'Accept':'application/json'})

Delete a replay

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.

curl -X DELETE "https://clickbase.so/api/sites/example.com/replays/{sessionId}" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

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

requests.delete(f'https://clickbase.so/api/sites/example.com/replays/{session_id}', headers={'Authorization': f'Bearer {token}', 'Accept':'application/json'})

Enable session replay

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 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, including track_session_replay: true). Status: 200 OK.

curl -X POST "https://clickbase.so/api/sites/example.com/replays/enable" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

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

requests.post('https://clickbase.so/api/sites/example.com/replays/enable', headers={'Authorization': f'Bearer {token}', 'Accept':'application/json'})