Privacy-First Session Replay: The Honest Retention Ladder

Session Replay Has a Hoarding Problem

Session replay is the most privacy-sensitive artifact a web analytics tool produces. A replay is not a counter or a score — it is a reconstruction of a person using your site: where their cursor hesitated, which form field they abandoned, which paragraph they read three times. That is exactly what makes replay invaluable for debugging and conversion work, and exactly why the default posture of the replay industry — record everything, keep it as long as possible — deserves more scrutiny than it gets.

Most replay tools treat retention as a storage quota. Pay more, keep more; deletion happens when the quota fills or the invoice lapses. Retention becomes an accident of pricing rather than a decision about data, and the result is an archive of recordings of real people that mostly nobody will ever watch — pure liability, zero insight.

ClickStream takes the opposite position. Privacy-first session replay means retention is a deliberate ladder: a defined window per plan, enforced in the codebase on both the write path and the read path, topping out at 90 days for every self-serve plan. Keeping less is the feature.

The Session Replay Retention Ladder

Five plans, five windows — the same tiers you see on the pricing page:

These numbers are not a marketing table that drifts away from reality. They come from the same per-plan feature map that gates the rest of the dashboard, and the internal pricing reference is kept in sync with the code that enforces them.

Hobby's replay access is deliberately a peek, not an archive: you can watch what is happening on your site right now — the last hour, at most 50 sessions in the live list. That is enough to sanity-check an install or watch a launch land, and not enough to accumulate a long-term behavioral archive on a free plan.

Enforced on Write and Read

A retention claim is worth very little if it is implemented as a dashboard filter over data that still exists. ClickStream enforces the ladder twice, at storage and at query:

• On write: the collector's live-session store — the Durable Object that holds replay frames at the edge — applies a per-plan TTL to stored sessions. Growth frames expire at 7 days, Scale at 30, Network at 90. Enterprise is the only tier where frames are never TTL-evicted, because the retention window there is defined by contract.
• On read: the dashboard's replay endpoints clamp every query to the same window before touching storage, and apply Hobby's 50-session peek cap to the live list.

The read-side clamp exists for a specific reason: downgrades. If an account drops from Scale to Growth, sessions older than 7 days become unreadable immediately — the read routes enforce the new window before the storage layer's cleanup cycle has even run. And because every gate is computed on the effective plan, which includes subscription status, a lapsed subscription shrinks the window automatically. It is the same posture ClickStream applies to billing: ingestion fails open so you never lose data to a payment hiccup, but entitlements fail closed.

What a ClickStream Replay Actually Shows

A replay reconstructs the session on top of the actual page, rendered at the visitor's recorded viewport size, from a stream of interaction frames: mouse movement, scrolling, clicks and touches, viewport resizes, input focus and edits, navigations, and tab-visibility changes — plus error, console, and network frames, so an engineer can line a JavaScript exception up with the exact moment of visible confusion that follows it. A timeline of session events runs alongside playback so you can jump straight to the interesting part instead of scrubbing.

One honesty detail worth calling out: every historical replay is labeled with its provenance. When full interaction frames were captured, playback is marked recorded. When they were not — replay disabled at the time, or an older session — the dashboard can synthesize approximate playback from the event timeline, and it labels that synthesized rather than passing reconstructed motion off as a recording.

What Never Leaves the Browser

Masking decisions are computed inside the visitor's browser, before a frame is ever queued for upload. The rules run in a strict precedence order:

• Passwords and hidden inputs are never captured — no value, not even a mask.
• Payment fields — matched by field name, cc-* autocomplete tokens, or a CVV-shaped value — are never serialized at all, not even as bullets, so a replay cannot leak the length or typing cadence of card data.
• Card-number-shaped values, including 12-plus-digit runs mid-typing, are dropped entirely regardless of what the field is called.
• SSN-shaped values are fully masked to bullets.
• Email values are partially masked: the first two characters, then the domain.
• Fields with sensitive names get a length-preserving bullet mask, so playback keeps the visible shape of the interaction without the content.

The value-based rules run regardless of field name — a card number typed into a field called notes still never serializes. And replay capture as a whole is opt-in at install time: the pixel records no replay frames unless you enable it (code below).

Bot-Filtered Replays

A meaningful share of any site's raw sessions is not human, and there is no worse use of a bounded retention window — or of your team's attention — than storing and scrubbing through a recording of a crawler paginating your catalog. Every ClickStream session carries a real-time bot verdict from the same detection engine that powers Signals — 11 bot categories, 158 named bots, and 38 AI agents. The Signals API exposes it as a four-way behavioral class — human, suspicious, likely bot, or bot — and the live view triages each session in plain language: real person, needs a check, or automated.

The live workspace ships a one-click Humans only filter that hides bot sessions from the replay list and shows a count of what it hid. Because billing counts human pageviews, bot sessions do not consume your pageview allowance either — automated traffic neither costs you money nor pollutes your replay queue. And when detection gets a real person wrong, there is an explicit correction path — the mark-it-human override — instead of a silently vanished session. For the full taxonomy of what gets caught, see the Bot Evasion Atlas.

Retention as a Privacy Feature

GDPR's storage-limitation principle says personal data should be kept no longer than necessary for its purpose. For session replay, the purpose is concrete: reproduce a bug, diagnose friction, verify a fix. That work has a useful life measured in days and weeks, not years. A recording from eleven months and forty releases ago is not evidence of anything about your current site — it is only risk.

A bounded window turns "we delete replay data" from a policy promise into a system property. It is a retention schedule you can state in a privacy policy or a data-processing agreement and back with code: on self-serve plans, the replay of any session is unreadable and evicted at most 90 days after it happened — 7 or 30 days on most plans, one hour on the free tier. Unlimited retention exists only on Enterprise, where a contract defines the terms. It is the same philosophy behind ClickStream's approach to compliance as scheduled jobs: an obligation you can read in the source outranks an obligation in a PDF.

What the Ladder Means Operationally

Each rung maps to a working rhythm rather than an arbitrary quota:

• Hobby — watch it live. The 1-hour, 50-session peek covers install verification and launch-day watching: open the live view, see real sessions render, confirm the pixel works.
• Growth — the weekly triage loop. Seven days covers "a user reported this on Tuesday": pull the sessions behind this week's bug report or frustration spike, watch them, file the fix.
• Scale — the monthly cycle. Thirty days covers a full funnel review or an A/B test washup, including before-and-after comparisons across a release.
• Network — the quarter. Ninety days is enough for seasonal comparisons and slow-burn UX investigations that span several releases.

The operational habit the ladder encourages: file the finding, not the footage. A replay is evidence for a decision — a bug ticket, a form redesign, a copy change. Extract the decision while the window is open. Your aggregates — scores, funnels, journeys — do not expire with the frames; only the pixel-level reconstruction does.

Turning Replay On

Replay capture is an opt-in flag on the pixel install. With the stable @clickstreamhq/sdk package (1.4.0):

npm install @clickstreamhq/sdk

import { installClickstreamPixel } from '@clickstreamhq/sdk';

installClickstreamPixel({
  apiKey: 'cs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
  endpoint: 'https://t.example.com', // your verified first-party tracking domain
  replay: true, // replay capture is opt-in
});

Script-tag installs get the same behavior with a data-replay="true" attribute on the pixel tag — the install guides cover tag managers and site builders. Either way, the pixel itself stays light: a 344-byte loader that pulls a ~56.5 KB gzipped bundle from your own subdomain.

The Bottom Line

• Retention is a product decision: Hobby gets a 1-hour peek capped at 50 sessions, Growth 7 days, Scale 30, Network 90, Enterprise by contract.
• It is enforced twice: per-plan TTLs where frames are stored, and window clamps on every dashboard read route — so downgrades take effect immediately.
• Sensitive input never leaves the browser: passwords and hidden fields are never captured; card and CVV data is never serialized even masked; SSNs and sensitive fields are bullet-masked; emails are partially masked.
• Bot traffic is labeled and filterable: a detection engine covering 11 bot categories, 158 named bots, and 38 AI agents flags automated sessions, one click hides them from the live replay list — and billing only counts human pageviews.
• Bounded retention is a commitment you can verify, not a storage quota you outgrow.

A replay you no longer need is not an asset. The honest thing to do with it is exactly what the ladder does: delete it — on schedule, in code.