See what a visitor saw: replay frames as screenshots
Turn session replays into static PNG screenshots at key moments like errors and rage clicks with the CLI or API to diagnose bugs fast.
On this page 8 sections
You can turn recorded session replays into still screenshots at critical moments using the CLI command vibiz replays frames <id> or by calling GET /v1/replays/:id/frames. Instead of scrubbing through minutes of recorded video, this extracts static PNG pictures of what a visitor saw when an error occurred, a form was abandoned, or a rage click happened. Each snapshot renders the page at the visitor's real viewport dimensions with sensitive customer data masked directly in the browser before upload.
When you triage bug reports or inspect checkout drop-offs, watching full video recordings takes time. Still frames pinpoint layout shifts, broken modals, and clicked elements in seconds.
Why inspect still frames instead of watching video
Reviewing full session recordings is useful when you need to understand user navigation flows, but it is slow when you only want to know why a specific button failed. Pulling frames gives you visual evidence formatted for quick review or automated checks:
- Instant triage: You see the exact layout state at the moment of failure without waiting for playback buffers.
- Visual annotations: Rage clicks and dead clicks automatically outline the target element and place a red dot on the visitor's pointer coordinates.
- Agent and automation friendly: AI tools and automated monitoring pipelines can inspect an image directly using vision models without running full media decoders.
- Bandwidth and storage savings: You download small PNGs of critical moments instead of pulling large multi-megabyte session chunks.
If you are setting up replay for the first time, read about our approach to privacy and data masking in session replays and how to configure session replay with consent first for strict jurisdictions.
What happens when a frame is generated
When you request frames for a replay, the server does not simply grab a video thumbnail. It reconstructs the DOM from the session's recorded event stream:
- Static reconstruction: The recorded page is rebuilt as a static document. No client-side JavaScript runs during this process, preventing malicious or broken scripts from executing.
- Asset loading: The renderer applies the site's original styles, images, and fonts so the visual presentation matches what the user saw.
- Viewport matching: The frame is photographed at the visitor's exact viewport width and height. If the user visited from a mobile phone, you receive a tall, narrow mobile screenshot rather than a scaled desktop view.
- Mask preservation: Masked text remains masked using bullet characters or asterisks. Any element marked with
data-vibiz-sensitiveor regions masked bydata-vibiz-maskappear as striped boxes. Passwords, payment card numbers, IBANs, and one-time codes are never stored or captured in the snapshot.
Because fonts that an application serves only to internal authenticated origins may not be accessible to the static renderer, those fonts fall back to system alternatives, but the layout structure remains true to the session.
Capturing screenshots with the CLI and HTTP API
You can inspect session frames directly from your terminal or pull them into your monitoring tools via the HTTP API.
To pull frames for a session and save them locally as PNG files:
vibiz replays frames rpl_123 --out ./framesThis fetches up to 6 default frames, prioritizing moments where something went wrong, and writes PNG files to the ./frames directory.
To inspect specific interaction types, use the --moments flag or request a frame at an exact timestamp:
# Capture only JavaScript errors and rage clicks
vibiz replays frames rpl_123 --moments error,rage_click --limit 4
# Capture a frame at exactly 14,200 milliseconds into the session
vibiz replays frames rpl_123 --at 14200 --out ./framesYou can make the exact same request using curl against the REST API:
curl "https://thelastapi.dev/v1/replays/rpl_123/frames?moments=error,rage_click" \
-H "Authorization: Bearer $VIBIZ_API_KEY"The API returns a JSON object detailing the rendered frames:
{
"frames": [
{
"kind": "error",
"offset_ms": 14200,
"page": "/checkout",
"label": "Uncaught TypeError: Cannot read properties of undefined",
"related": "button#submit-order",
"viewport": { "width": 390, "height": 844 },
"status": "ready",
"image": {
"url": "https://thelastapi.dev/v1/files/fl_frame_abc123.png",
"expires_at": "2026-11-12T13:00:00.000Z"
},
"cached": false,
"cost_micro_usd": 1500,
"error": null
}
],
"cost_micro_usd": 1500,
"new_frames": 1
}You can also use the scoped project endpoint: GET /v1/projects/:id/replays/:replayId/frames. Full documentation on session parameters is available in our guide to Analytics and replay.
Which moments trigger screenshots
By default, the replay system scores and selects up to 6 key frames per session (configurable up to 12 via ?limit=). It prioritizes failures first so you see broken experiences without digging.
| Moment kind | What triggers it | Visual indicator on frame |
|---|---|---|
first_page | The start of the visitor's session | Clean page layout |
new_page | Navigation to a new pathname | Clean page layout |
error | Uncaught JavaScript exception | The page state when the error fired |
rage_click | Rapid clicks on an unresponsive element | Element outlined; pointer shown as a red dot |
dead_click | Click on an interactive-looking element with no effect | Element outlined; pointer shown as a red dot |
abandoned_form | User inputs data into a form but leaves without submitting | Visible inputs with typed values (sensitive masked) |
end | The last interaction before the tab closes | Final rendered DOM state |
When monitoring team health, these signals bubble up to the console. As covered in Mission Control and health checks, sessions with repeated rage clicks or error spikes automatically generate warnings on your project board.
Pricing, caching, and link lifetimes
Frame generation balances convenience and minimal compute costs:
- Screenshot metering: Each newly generated frame is metered and priced as a standard page screenshot (
cost_micro_usd). - Free repeated reads: Once a frame has been rendered for a specific moment or timestamp, subsequent reads have
cached: trueand cost $0 (cost_micro_usd: 0). - Temporary access URLs: Generated image links (
image.url) remain valid for 1 hour. If a link expires, calling the endpoint again issues fresh signed links at zero cost without re-rendering the snapshot. - Storage lifecycle: Frame images are stored alongside the parent session recording. When the replay reaches the end of its retention window (30 days by default, or 1 to 90 days as set by
retention_days), its frames are permanently deleted along with the session chunks. Replay storage itself is recorded at $0.023 per GB-month.
If you want traffic visibility without storing DOM sessions, you can review our guide to cookieless web analytics.
Common errors when requesting frames
When an issue prevents snapshot creation, the API returns structured error codes:
# Example error when a session had no initial DOM snapshot
HTTP/1.1 409 Conflict
Content-Type: application/json
{
"error": {
"code": "conflict",
"reason": "no_snapshot",
"message": "Replay does not contain a full DOM snapshot."
}
}- 409 Conflict (
reason: no_snapshot): This occurs if recording started late or the initial DOM snapshot chunk failed to upload. The frame engine cannot reconstruct styles or DOM hierarchy without a base snapshot. - 400 Invalid Request (
field: at): You requested an offset timestamp (such as--at 45000) that exceeds the total duration of the session. Check the timeline'soffset_msbefore querying single frames. - 200 OK with
status: failed: If an individual image render encounters an issue, the HTTP call still returns 200, but the specific frame object containsstatus: "failed"and anerrorproperty explaining why. Retrying the request only attempts to render the failed items, while successful frames remain cached.
Next steps
To inspect problem sessions from the last week, run vibiz replays --errors --period 7d to locate troubled session IDs. Once you have a session ID, run vibiz replays frames <id> --out ./debug to pull down static images of every error and rage click for quick local review.
===BODY===
Frequently asked questions
Can I take a screenshot at an arbitrary moment in a session?
Yes. Pass the `--at <ms>` flag in the CLI or the `?at=<ms>` query parameter in the API to capture the exact DOM state at any millisecond offset from the start of the session.
Are passwords and credit card numbers visible in the screenshots?
No. Passwords, payment card numbers, IBANs, and one-time codes are masked directly inside the visitor's browser before upload, and blocked elements set with `data-vibiz-sensitive` appear as striped boxes in the generated frame.
How long do frame screenshot links remain accessible?
The signed image URLs returned by the API remain active for 1 hour. Calling the frames API again produces fresh URLs for existing frames at no additional cost.
Do repeated frame requests cost extra API credits?
No. Each unique moment or timestamp is metered only the first time it is rendered; any subsequent request for that frame is marked as cached and costs nothing. ===FAQ===