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).

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`

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 actor — 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.

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.

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