thelastapi
Get started free

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:

  1. 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.
  2. Asset loading: The renderer applies the site's original styles, images, and fonts so the visual presentation matches what the user saw.
  3. 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.
  4. Mask preservation: Masked text remains masked using bullet characters or asterisks. Any element marked with data-vibiz-sensitive or regions masked by data-vibiz-mask appear 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:

Terminal
vibiz replays frames rpl_123 --out ./frames

This 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:

Terminal
# 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 ./frames

You can make the exact same request using curl against the REST API:

Terminal
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:

JSON
{
  "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 kindWhat triggers itVisual indicator on frame
first_pageThe start of the visitor's sessionClean page layout
new_pageNavigation to a new pathnameClean page layout
errorUncaught JavaScript exceptionThe page state when the error fired
rage_clickRapid clicks on an unresponsive elementElement outlined; pointer shown as a red dot
dead_clickClick on an interactive-looking element with no effectElement outlined; pointer shown as a red dot
abandoned_formUser inputs data into a form but leaves without submittingVisible inputs with typed values (sensitive masked)
endThe last interaction before the tab closesFinal 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.

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: true and 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:

Terminal
# 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's offset_ms before 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 contains status: "failed" and an error property 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===