Servers
Stream recording events
Stream recording event payloads over a WebSocket connection. This is the default method used in our Browser Client. See WebSocket event streaming for more details, or use the HTTP event collection route for a simpler method.
Note: Since browsers cannot send custom headers with WebSocket requests, the browser client automatically appends your API key as a query parameter (?token=your-api-key) to the WebSocket URL.
Please ignore reference to the Bearer HTTP Authentication header here until we can update this documentation to include support for interacting with websockets. The GET method is correct insofar as it refers to the initial upgrade part of the websocket connection negotiation.
Authorizations
Public API key for authentication.
"Bearer public_key_rr_1Q8AX5B5218353Q1AQNF2129YH5VAH02"Parameters
Path Parameters
The recording ID
"000e8400-e00b-00d0-a716-446655440000""uuid"Query Parameters
Enable debug mode
"true"Payload content type. Defaults to application/x-ndjson when omitted.
"application/x-ndjson""application/ndjson""application/json""application/x-ndjson"Optional compression applied to the payload frames. Defaults to identity.
"gzip""br""zstd""gzip"Responses
WebSocket upgraded successfully.
Get recording events
Retrieve the event stream for a single recording.
Authorizations
Bearer token for authentication. Use your private API key as the token.
"Bearer secret_key_rr_1Q6AX5B5218353Q1AQNF2129YH5VAH02"Your tenant (organisation) identifier. Included automatically in presigned URLs generated by the listing endpoints.
The name/label of the signing key configured in your rrweb Cloud account. e.g. "key-2024-12"
Expiration timestamp (UNIX seconds)
SHA256 over the constructed string "GET /recordings/{recordingId} {tenantId} {expires}". Please get in contact if you need to calculate this manually.
Parameters
Path Parameters
The recording ID
"000e8400-e00b-00d0-a716-446655440000""uuid"Responses
Successfully retrieved recording events
Create recording events
Append recording events in batch mode via POST. This is available for clients or environments which don't support WebSocket event streaming.
Authorizations
Public API key for authentication.
"Bearer public_key_rr_1Q8AX5B5218353Q1AQNF2129YH5VAH02"Parameters
Path Parameters
The recording ID
"000e8400-e00b-00d0-a716-446655440000""uuid"Query Parameters
Enable debug mode
"true"Request Body
Responses
Successfully accepted recording events
Get recording metadata
Retrieve only the searchable metadata key-value pairs for a single recording.
Authorizations
Bearer token for authentication. Use your private API key as the token.
"Bearer secret_key_rr_1Q6AX5B5218353Q1AQNF2129YH5VAH02"Your tenant (organisation) identifier. Included automatically in presigned URLs generated by the listing endpoints.
The name/label of the signing key configured in your rrweb Cloud account. e.g. "key-2024-12"
Expiration timestamp (UNIX seconds)
SHA256 over the constructed string "GET /recordings/{recordingId} {tenantId} {expires}". Please get in contact if you need to calculate this manually.
Parameters
Path Parameters
The recording ID
"000e8400-e00b-00d0-a716-446655440000""uuid"Responses
Successfully retrieved recording metadata
Capture metadata
Attach searchable metadata to a recording so you can query recordings by customer, device, rollout state, or any other field. See Recording metadata for implementation guidance.
Authorizations
Public API key for authentication.
"Bearer public_key_rr_1Q8AX5B5218353Q1AQNF2129YH5VAH02"Parameters
Path Parameters
The recording ID
"000e8400-e00b-00d0-a716-446655440000""uuid"Request Body
Responses
Successfully captured recording metadata
Get recording
Retrieve a recording descriptor, including metadata and related links. Bearer-token requests can set includeEvents=true to embed the replayable event stream in the response. Presigned detail URLs remain descriptor-only; use the signed events link for presigned event access.
Authorizations
Bearer token for authentication. Use your private API key as the token.
"Bearer secret_key_rr_1Q6AX5B5218353Q1AQNF2129YH5VAH02"Parameters
Path Parameters
The recording ID
"000e8400-e00b-00d0-a716-446655440000""uuid"Query Parameters
Include presigned recording links in the detail response.
trueInclude the recording event stream in the detail response.
trueResponses
Successfully retrieved recording details
Compose replay
Get events corresponding to one or more recordingIds from rrweb Cloud in a replayable stream.
By default intermingled events from multiple recordings are grouped according to page view (FullSnapshot), and recordings are split up so that each page view plays in full before moving on to the next page view, which may come from a different recording depending on which one occurred first.
Recording timestamps are renumbered from zero to support the new ordering, and the original absolute timestamp is transferred into the originalTimestamp key.
Authorizations
Bearer token for authentication. Use your private API key as the token.
"Bearer secret_key_rr_1Q6AX5B5218353Q1AQNF2129YH5VAH02"Parameters
Query Parameters
A recording metadata parameter (or a set of parameters) by which you want to compose a single replay. Use metadata[key]=value syntax.
{
"sessionId": "session-123"
}Responses
Successfully retrieved recording events
Get replay
Retrieve merged metadata and replayable events for recordings sharing a metadata key and value.
Authorizations
Bearer token for authentication. Use your private API key as the token.
"Bearer secret_key_rr_1Q6AX5B5218353Q1AQNF2129YH5VAH02"Your tenant (organisation) identifier. Included automatically in presigned URLs generated by the listing endpoints.
The name/label of the signing key configured in your rrweb Cloud account. e.g. "key-2024-12"
Expiration timestamp (UNIX seconds)
SHA256 over the constructed string "GET /recordings/{recordingId} {tenantId} {expires}". Please get in contact if you need to calculate this manually.
Parameters
Path Parameters
The metadata key used to group recordings into replays
"sessionId"1100The metadata value identifying this replay group
"sess-123"1500Responses
Successfully retrieved replay metadata and events
Get replay events
Retrieve only the replayable event stream for a replay group.
Authorizations
Bearer token for authentication. Use your private API key as the token.
"Bearer secret_key_rr_1Q6AX5B5218353Q1AQNF2129YH5VAH02"Your tenant (organisation) identifier. Included automatically in presigned URLs generated by the listing endpoints.
The name/label of the signing key configured in your rrweb Cloud account. e.g. "key-2024-12"
Expiration timestamp (UNIX seconds)
SHA256 over the constructed string "GET /recordings/{recordingId} {tenantId} {expires}". Please get in contact if you need to calculate this manually.
Parameters
Path Parameters
The metadata key used to group recordings into replays
"sessionId"1100The metadata value identifying this replay group
"sess-123"1500Responses
Successfully retrieved replay events
Get replay metadata
Retrieve only the merged metadata for a replay group.
Authorizations
Bearer token for authentication. Use your private API key as the token.
"Bearer secret_key_rr_1Q6AX5B5218353Q1AQNF2129YH5VAH02"Your tenant (organisation) identifier. Included automatically in presigned URLs generated by the listing endpoints.
The name/label of the signing key configured in your rrweb Cloud account. e.g. "key-2024-12"
Expiration timestamp (UNIX seconds)
SHA256 over the constructed string "GET /recordings/{recordingId} {tenantId} {expires}". Please get in contact if you need to calculate this manually.
Parameters
Path Parameters
The metadata key used to group recordings into replays
"sessionId"1100The metadata value identifying this replay group
"sess-123"1500Responses
Successfully retrieved replay metadata
List replays
List replay groups for a metadata key. Each replay group represents one metadata value and one or more recordings sharing that value.
Authorizations
Bearer token for authentication. Use your private API key as the token.
"Bearer secret_key_rr_1Q6AX5B5218353Q1AQNF2129YH5VAH02"Parameters
Path Parameters
The metadata key used to group recordings into replays
"sessionId"1100Query Parameters
Maximum number of replays to return (1-100, default: 50)
"50"Number of replays to skip (default: 0)
"0"Include presigned replay URLs in the response.
trueResponses
Successfully listed replays grouped by metadata value
List recordings
Query recordings by metadata filters or by most recent. Multiple filters are combined with AND logic.
Authorizations
Bearer token for authentication. Use your private API key as the token.
"Bearer secret_key_rr_1Q6AX5B5218353Q1AQNF2129YH5VAH02"Parameters
Query Parameters
Filter recordings by metadata key-value pairs. Use metadata[key]=value syntax (URL-encode keys and values with encodeURIComponent). eg. metadata[userId]=user-123&metadata[plan]=pro
{
"userId": "user-123",
"plan": "pro"
}Maximum number of results to return (1-100, default: 50)
"50"Number of results to skip (default: 0)
"0"Include presigned event URLs in the response.
trueResponses
Successfully retrieved recordings
Get recording statistics
Get statistics about recordings including total count, count for this month, and storage usage.
Authorizations
Bearer token for authentication. Use your private API key as the token.
"Bearer secret_key_rr_1Q6AX5B5218353Q1AQNF2129YH5VAH02"Responses
Successfully retrieved recording statistics
Get recording player
Serves the recording player HTML page. Request /recordings/{recordingId}/player.html or send Accept: text/html for the HTML representation. File extensions take precedence over the Accept header when both are present.
Authorizations
Bearer token for authentication. Use your private API key as the token.
"Bearer secret_key_rr_1Q6AX5B5218353Q1AQNF2129YH5VAH02"Your tenant (organisation) identifier. Included automatically in presigned URLs generated by the listing endpoints.
The name/label of the signing key configured in your rrweb Cloud account. e.g. "key-2024-12"
Expiration timestamp (UNIX seconds)
SHA256 over the constructed string "GET /recordings/{recordingId} {tenantId} {expires}". Please get in contact if you need to calculate this manually.
Parameters
Path Parameters
The recording ID
"000e8400-e00b-00d0-a716-446655440000""uuid"Query Parameters
Show the control bar (default: true).
"true"Autoplay on load (default: false).
"false"Player display mode. standard renders the full player page, minimal strips surrounding chrome for embeds, and capture uses the full-viewport layout optimized for screenshots.
"standard"Playback speed from 0.25 to 4 (default: 1). Values outside this range return 400.
"1"Playback position selector. Supports offset, percent, and epoch formats: offset:5000, offset:-5000, percent:50, or epoch:1702900000000. Defaults to offset:0.
"offset:0"Optional same-origin or relative events URL override. Used internally with presigned event URLs for player and screenshot rendering.
"https://api.example.com/recordings/000e8400-e00b-00d0-a716-446655440000/events?tenantId=tenant-123&expires=1700000000&keyId=key-2025-12&signature=abcdef"Responses
Recording player HTML page
Get recording screenshot
Generates a screenshot of a recording at a specific playback position. Supports extension-based negotiation via /recordings/{recordingId}/screenshot.png, .jpeg, or .webp; file extensions take precedence over the Accept header. This endpoint exposes only time, width, height, quality, and the negotiated output format from the underlying browser-rendering service.
Authorizations
Bearer token for authentication. Use your private API key as the token.
"Bearer secret_key_rr_1Q6AX5B5218353Q1AQNF2129YH5VAH02"Your tenant (organisation) identifier. Included automatically in presigned URLs generated by the listing endpoints.
The name/label of the signing key configured in your rrweb Cloud account. e.g. "key-2024-12"
Expiration timestamp (UNIX seconds)
SHA256 over the constructed string "GET /recordings/{recordingId} {tenantId} {expires}". Please get in contact if you need to calculate this manually.
Parameters
Path Parameters
The recording ID
"000e8400-e00b-00d0-a716-446655440000""uuid"Query Parameters
Playback position selector. Supports offset, percent, and epoch formats: offset:5000, offset:-5000, percent:50, or epoch:1702900000000. Defaults to offset:0.
"offset:0"Width in pixels from 1 to 4096. Defaults to 1280 when omitted. If height is provided and width is omitted, width is derived from the recording viewport ratio when metadata is available. Values outside this range return 400.
"1280"Height in pixels from 1 to 4096. Defaults to 720 when omitted and recording viewport metadata is unavailable. If width is provided or both dimensions are omitted, height is derived from the recording viewport ratio when metadata is available. Values outside this range return 400.
"720"Quality from 1 to 100 for JPEG and WebP output (default: 80). Ignored for PNG.
"80"Responses
Screenshot image