User retention is a key metric that tells you if your product is actually keeping people engaged. PostHog's Retention feature lets you define a starting event (like signing up) and a return event (like logging back in), then automatically calculates how many of those users return over time. This gives you a clear view of whether your product is sticky or if you're leaking users.
Set Up Retention Tracking in the Dashboard
PostHog's Retention tab is the quickest way to measure how many users come back after their first action.
Navigate to the Retention Tab
Go to Discover > Retention in your PostHog project. This opens the retention analysis interface where you'll define which events indicate a user returning.
import posthog from 'posthog-js';
posthog.init('your-api-key', {
api_host: 'https://app.posthog.com'
});Select Your Starting Event
In the retention query builder, set the Starting event to the action that defines a new user cohort. Common choices are $pageview, sign_up, or user_login. PostHog will group users by when they first performed this event.
posthog.capture('sign_up', {
source: 'homepage',
plan: 'free'
});Define Your Return Event
Set the Returning event to any action that indicates the user is active again. This could be $pageview (they loaded a page), user_login, or clicked_feature. PostHog counts a user as "retained" if they perform this event within the time bucket.
posthog.capture('user_login', {
login_method: 'email'
});Choose Your Retention Interval
Select the time bucket: Day, Week, or Month. Weekly retention is the most common choice for SaaS products. This determines how PostHog groups cohorts and calculates return windows.
Add Filters and Segments
Click Filters to narrow down which users you're tracking—for example, only users from a specific country or on a paid plan. Use Breakdown by to split retention by properties like region or subscription tier.
posthog.identify('user-123', {
email: '[email protected]',
plan: 'pro',
country: 'US',
signup_date: new Date()
});$pageview as your return event to see if users just return to your app at all, versus more specific actions like clicked_dashboard to see feature engagement.Send the Right Events to PostHog
Retention calculations depend on clean, consistent event tracking. You need a clear definition of what a "returning user" looks like in your app.
Decide on a Return Event
The return event should match your product's definition of an active user. For a SaaS tool, this might be user_login. For a content site, $pageview is often enough. For a mobile app, you might use app_opened. Be consistent—if you change events later, your retention numbers will shift.
// Option 1: Track login as the return signal
posthog.capture('user_login', {
device: 'web'
});
// Option 2: Use page view for broader tracking
posthog.capture('$pageview', {
path: window.location.pathname
});Prevent Duplicate Starting Events
Make sure your starting event only fires once per user (on sign-up or first visit). PostHog tracks this automatically with session IDs, but double-check that you're not capturing sign_up multiple times due to form resubmissions or page reloads.
if (!localStorage.getItem('user_signed_up')) {
posthog.capture('sign_up', {
method: 'email',
signup_at: new Date().toISOString()
});
localStorage.setItem('user_signed_up', 'true');
}Include User Properties with Events
When you capture your starting event, add properties like plan, country, source, or cohort_date. These let you segment your retention analysis later—for example, "Do pro users have better retention than free users?"
posthog.identify('user-456', {
email: '[email protected]',
company: 'Acme Inc',
plan: 'enterprise'
});
posthog.capture('sign_up', {
plan: 'enterprise',
cohort: 'wave_1',
acquisition_channel: 'partner'
});Read and Act on Retention Data
Once PostHog calculates retention, interpret the numbers and use them to guide product decisions.
Understand the Retention Table
The retention view shows a table where rows are cohorts (e.g., "users who signed up week of March 1") and columns are periods (Week 0, Week 1, Week 2). Each cell shows the percentage of that cohort that returned. A healthy SaaS product typically sees 40–70% weekly retention after the first week.
Segment Retention by User Properties
Use the Breakdown by dropdown to compare retention across groups. For example, break down by plan to see if paying customers stick around longer. Or break down by signup_source to see which acquisition channels bring stickier users.
// Query PostHog API for retention data
const response = await fetch(
'https://app.posthog.com/api/projects/YOUR_PROJECT_ID/insights/',
{
method: 'GET',
headers: {
'Authorization': `Bearer YOUR_PERSONAL_API_KEY`,
'Content-Type': 'application/json'
}
}
);
const data = await response.json();Export and Track Over Time
Click Export to save retention data as CSV. Track retention weekly in a spreadsheet or dashboard to spot trends—if retention suddenly drops 10%, something in your product changed. If it rises, you did something right.
Common Pitfalls
- Using
$pageviewas both starting and returning event—this inflates numbers because every page load counts as a return. Usesign_upas start anduser_loginas return instead. - Forgetting time zones—PostHog uses UTC by default. If your users span regions, cohort boundaries may not align with your actual user weeks.
- Setting your return event too rare (e.g., only tracking
paid_upgrade)—this makes even healthy products show near-zero retention. Pick an event most users do regularly. - Changing your events mid-analysis—if you swap events halfway through, historical retention won't match your new definition. Lock in events before analyzing.
Wrapping Up
You now have retention tracking set up in PostHog. Define your starting event (sign-up), pick a returning action (login or pageview), and let PostHog calculate week-over-week cohort retention. Check it weekly to spot trends and decide where to focus product improvements. If you want to track this automatically across tools, Product Analyst can help.