Retention is the metric that separates growing products from ones that just acquire users. If you're not measuring who comes back, you're flying blind. PostHog's retention insight shows exactly how many users return after their first action—but only if you're tracking the right events.
Setting Up Events for Retention Tracking
Before you can measure retention, you need to define what 'using your product' means. This usually means tracking a key action—signup, first login, or a specific feature usage.
Initialize PostHog and identify users
Add the PostHog JavaScript SDK to your app and set it up in your main application file. Replace phc_YOUR_PROJECT_API_KEY with your actual project API key from Settings > Project > API Key.
import posthog from 'posthog-js'
posthog.init('phc_YOUR_PROJECT_API_KEY', {
api_host: 'https://app.posthog.com',
loaded: (ph) => {
ph.identify(userId, {
email: userEmail,
signup_date: new Date().toISOString(),
plan: userPlan
})
}
})Capture your initial action event
Define the event that marks a user's first meaningful interaction. This is typically signup, account creation, or dashboard access. Use descriptive event names and include relevant properties for segmentation.
// Track when user completes signup
posthog.capture('user_signup', {
signup_method: 'email',
referral_source: utm_source,
$set: {
plan_selected: 'pro',
company_size: 'enterprise'
}
})
// Or track first feature usage
posthog.capture('feature_first_used', {
feature: 'dashboard',
time_to_action: 120
})Track return visits
Capture a consistent event each time the user returns to your product. This is usually a page view, login, or session start. PostHog's retention insight will compare your initial action against this return event.
// Track return visits - fire on every session or page load
posthog.capture('user_session', {
session_duration: sessionLength,
features_used: ['dashboard', 'reports'],
returning_user: true
})
// Or track specific returning action
posthog.capture('feature_used', {
feature: 'dashboard',
time_spent: 45
})page_view as both your first action and return event, the retention graph will be meaningless. Use distinct events like user_signup for initial and user_session for returns.Creating and Reading a Retention Insight
Once your events are flowing, PostHog's retention insight will show you exactly how many users return after their initial action.
Open the Retention insight builder
Go to Insights in the left sidebar, click + New Insight, and select Retention. This opens PostHog's retention configuration panel where you'll define your initial and returning events.
// Retention insights are UI-driven, but you can fetch saved insights via API
const response = await fetch(
'https://app.posthog.com/api/projects/{project_id}/insights',
{
method: 'GET',
headers: {
'Authorization': `Bearer ${POSTHOG_API_TOKEN}`,
'Content-Type': 'application/json'
}
}
)
const insights = await response.json()
const retentionInsight = insights.results.find(i => i.insight === 'RETENTION')Configure retention parameters
Set your Returning event to the event users should repeat (e.g., user_session). Set your Initial event to the action that defines new users (e.g., user_signup). Choose your time interval (day, week, or month) and click Update.
// When you configure retention in PostHog, it's tracking this pattern:
// Users who did 'user_signup' on Day 0
// Then measure what % did 'user_session' on Day 1, 2, 3, etc.
const retentionMetric = {
initial_event: 'user_signup',
returning_event: 'user_session',
interval: 'day' // or 'week' or 'month'
}
// PostHog shows you a table like:
// Day | Users in cohort | Day 1 | Day 2 | Day 3 | Week 1 | Week 2
// 0 | 1000 | 45% | 28% | 22% | 12% | 8%Add property filters to segment retention
Click Add filter and select a user property (e.g., plan = 'pro' or signup_source = 'organic'). PostHog will recalculate the retention curve for only users matching that property. This reveals which segments have the best retention.
// Ensure your events include segmentation properties
posthog.capture('user_signup', {
plan: 'pro', // segment by plan
company_size: 'enterprise',
referral_source: 'partner',
country: 'us',
industry: 'saas'
})
// Then in PostHog UI, add filters:
// plan = 'pro' (see pro user retention)
// company_size = 'enterprise' (see enterprise retention)
// This lets you compare: do paid users retain better than free users?Interpreting Retention and Taking Action
Your retention table tells you a story: how many users stick around, and which segments engage the most.
Read your retention curve
The table shows your cohort size (Day 0) and the percentage returning on each subsequent day. A healthy B2B product sees 40-50% return the next day. A declining curve is normal; look for where it stabilizes—that's your core engaged users.
// Example retention output interpretation:
// Day 0: 1000 users signed up
// Day 1: 45% returned (450 users)
// Day 2: 28% returned (280 users)
// Day 7: 12% returned (120 users)
// Day 30: 8% returned (80 users)
// What this means:
// - You lose most users in the first week (normal churn)
// - 8% of your signup cohort becomes power users
// - Focus on: how do you move more users from 'lost' to 'core'?Compare segments to find your best users
If you filtered by plan, company size, or signup source, compare the curves. Paid users retaining at 15% month-1 vs. free users at 3%? That's a huge signal. Organic users vs. paid ads? That tells you something real about product-market fit.
// Example: comparing retention across plans
// Add multiple filters in sequence to build segments:
// Filter 1: plan = 'pro'
// Result: 15% month-1 retention
// Filter 2: plan = 'free'
// Result: 3% month-1 retention
// Insight: Pro users are 5x more likely to return.
// Action: Look at what pro users do in their first week—can you
// get free users to do that same thing?Common Pitfalls
- Using the same event for both initial and returning actions—your retention curve becomes meaningless because every user 'returns' the moment they sign up.
- Not attaching properties to events—you'll capture all the right events but won't be able to segment by plan, source, or company later when you want to dig deeper.
- Checking retention too early—you need at least 2-3 weeks of data for patterns to emerge. Checking day-by-day will show only noise.
- Forgetting to define what 'return' means—if you don't actively capture a return event, PostHog has nothing to measure retention against.
Wrapping Up
You now have a working retention insight showing exactly which users stick around and which churn. Segment by plan, source, or company size to find your highest-engagement user profiles, then acquire more of them. If you want to track retention automatically across tools and spot trends before they impact revenue, Product Analyst can help.