Skip to main content
Retention is a ratio between two definitions. Group people by when and count how many of them came back when else — change either half and the same product retains 40% or 80%. This page is the halves. The panel draws it under Analytics → Retention, behind analytics:read.

​
What a cohort is

A UTC week, Monday-start. A contact belongs to the week of its first $auth.identified event — the fact UserKit publishes the moment somebody stops being anonymous. When there is no such event, the week the contact was created is used instead: a contact born over POST /v1/contacts or a CSV import fires no auth fact, and dropping those would silently exclude every tenant who migrated their users in. Anonymous visitors have no cohort at all. A visitor gets a contact row and a session, so its events carry a contact_id — which is exactly why “has a contact” cannot be what a cohort counts. Identified only, the same exclusion that keeps visitors off your active-contact meter.

​
What retained means

The contact produced at least one authenticated event in that week: a sign-in, or anything it did while signed in. Not a page view from a logged-out browser, and not an email open. Week 0 is the cohort week itself, so its retention is 1 by construction — a cohort is 100% of itself. Offsets run densely up to the current week, so a week nobody came back in is a zero on the chart rather than a hole in it.

​
Reading it

contacts is the cohort’s size and the denominator of every retention below it. retention is a fraction between 0 and 1, not a percentage — a percentage is one multiplication away and a ratio does not lose precision on the way to a chart. A cohort three weeks old has three entries in weeks. The fourth is not a zero; it has not happened yet, and drawing one would report a churn that no week has had the chance to contradict.

​
Eight weeks, recomputed

A nightly job recomputes the last eight cohort weeks whole, from your raw events, and upserts the result. Running it twice lands the same numbers. Rows older than that window freeze where the last run left them. That freeze is the point: your raw event history can age out without the chart moving underneath it. It also means a correction reaches a cohort only while it is still inside the window. The default range covers those eight weeks. from and to narrow it, and they are compared against the cohort’s Monday — a cohort is charted whole or not at all, because half a curve read as the whole one is not a rougher retention number, it is a wrong one. Your plan’s analytics retention window applies here the same way it applies to the event counts.

​
What an empty answer means

status is the field that keeps an empty cohorts from lying, and it exists because the two ways to get one call for opposite actions: It is ready whenever cohorts is non-empty. The distinction between the other two is asked of your contacts rather than guessed at from the emptiness: reporting “no data” to somebody whose job never ran is exactly the reassurance that stops them looking.

​
Whose midnight

Weeks are UTC at storage and your organization’s timezone at display, the same rule the event counts and the revenue metrics follow. Deciding it once is what lets a retention curve and an event chart be laid over each other.