Retention & Churn

The Retention & Churn page (sidebar Retention) shows two complementary views of how well your application keeps users coming back: a cohort retention matrix and a churn trend chart. Both are scoped to a single product at a time.

Prerequisites

Plan: available on all plans, including Trial.
Permission: view_reports.

How to load data

Open Retention in the sidebar. You’ll see a “Select a product to view retention and churn data” prompt.
Pick a Source App from the product selector. The page loads as soon as you do.
Optional: narrow by Source Version (defaults to blended across all versions) and Date range (defaults to the last 30 days).
Optional: switch Count by between User (the default) and Account. Counting by account measures retention at the customer-organisation level — see Account-level retention below. The Account option is locked with a tooltip on Trial / Starter / Pro; it requires Business or Enterprise.

If your selected date range starts before your plan’s retention window, a banner appears:

Data before [date] has been purged per your plan’s retention policy.

Beacon silently moves the start date up to the earliest data you still have — the page renders normally, just over the retained portion.

Retention cohorts

A cohort is the set of actors first seen on a specific date for the selected product (and version, if filtered). Beacon then measures, for each cohort, how many of those actors were still active 1 / 7 / 14 / 30 / 60 / 90 / 120 / 150 / 180 / 270 / 365 days later.

The page renders three views of this data:

Summary stats at the top — total cohorts in the window, average day-1 retention, etc.
Average retention curve — an area chart showing the mean retention rate at each offset (day 1 / 7 / 14 / 30 / 60 / 90), averaged across every cohort in the window. One curve, not one per cohort.
Retention heatmap — a grid with one row per cohort date and one column per offset. Darker cells mean higher retention. Offsets that haven’t elapsed yet (e.g., day-90 for a cohort 30 days old) are blank.

A plain-language summary line above the chart reads something like “On average, 42.1% of new users return the next day, and 17.3% are still active after 2 weeks.” It falls back to the day-7 figure if day-14 isn’t available for any cohort yet.

Data freshness: Retention cohorts are recomputed overnight. Activity from today appears in the table tomorrow — the table is not real-time.

Churn trend

The Churn Trend chart at the bottom of the page shows what fraction of active users dropped off between consecutive periods. Toggle between Weekly (Mon-Sun buckets) and Monthly (calendar month buckets).

For each period pair (current → next):

Active actors — distinct actors with at least one event in the current period.
Churned actors — active in the current period who did NOT return in the next period.
Churn rate — churned ÷ active as a percentage.

Incomplete periods (the current ongoing week or month) are excluded so the chart only shows finished comparisons.

The churn chart pulls live data — events ingested moments ago count toward current-period actives once aggregation accepts them.

Cohort sizes are based on `actor_id` (or `account_id`)

When counting by user, what counts as a “user” is the actor_id your SDK sends. If you send anonymous actor IDs that change each session, every session looks like a new user — and your retention drops to near zero. Send a stable per-user identifier (a license key, account ID, hashed email, etc.) so the same person carries the same actor_id across sessions.

When counting by account, the cohort unit is the account_id instead. Events without an account_id are excluded from the computation entirely.

Both retention and churn respect the Source App and (optional) Source Version filters. If you don’t supply a version, both metrics blend across every version of the product.

Account-level retention

When Count by is set to Account:

A cohort is the set of customer accounts first seen on a date for the selected product. The “first seen” timestamp is taken from the earliest event Beacon observed under that account_id.
An account is retained at offset N if any event under that account_id occurred during the offset period — at least one user in the customer’s organisation was active in the window.
The churn trend counts distinct accounts active in each period and what fraction failed to return in the next.

Use this view when your business question is “how many customer organisations are coming back?” rather than “how many individual users are coming back?” Both questions matter for B2B products and they often answer differently — one user from a 50-seat customer returning every week makes the account look retained even if 49 individual seats have churned.

Common questions

Day-90 for my newest cohort is blank. The window hasn’t elapsed yet. The cell will populate after 90 days have passed since that cohort’s date.

Retention rates look much lower than I expected. Most likely: anonymous-changing actor_id. Check the Actor Identities page to see how many distinct actor IDs you’re emitting per day. If the count looks much larger than your real user count, the SDK is rotating IDs.

Churn looks fine but retention is dropping. They measure different things. Churn is binary (return / didn’t return) over a fixed period; retention measures activity at specific offsets after a user’s first day. A retention drop at day-14 with steady weekly churn usually means second-week engagement is weakening even though most users come back at least once a month.

Can I export the data? Not from this page today. Both GET /v1/reports/retention and GET /v1/reports/churn are available for direct API consumption — see the API reference.

→ Exceptions