You need to know if users come back. Mixpanel's retention report shows you exactly what percentage of users return after their first action, broken down by cohort. It's the fastest way to spot if your product is sticky—or where you're losing people.
Setting Up Your Retention Report
Before you measure retention, Mixpanel needs to know which events define a "new user" cohort and which events count as a return.
Step 1: Track the right events
Retention starts with events. Make sure your app sends an event on signup or first use (the cohort event), and another event when users return (the retention event). Use mixpanel.track() to send both.
// Track signup as your cohort event
mixpanel.track('Signed Up', {
plan: 'starter',
source: 'organic'
});
// Track any return action as retention event
mixpanel.track('Dashboard Opened', {
user_id: user.id,
timestamp: new Date()
});Step 2: Go to Insights → Retention
In Mixpanel, click Insights in the left sidebar, then select Retention from the dropdown. This opens the retention report builder.
// Ensure users are identified for better cohort grouping
mixpanel.identify('user-123');
mixpanel.people_set({
'$email': '[email protected]',
'plan': 'pro',
'signup_date': new Date().toISOString()
});Step 3: Select your retention event
Choose the event that marks a user as "retained." For SaaS, this is often Dashboard Opened, Project Viewed, or API Call Made. Click the Retention event dropdown and pick the action that signals active use.
// Example: API call as retention signal
mixpanel.track('API Called', {
endpoint: '/analytics/events',
method: 'GET',
response_time: 142,
status: 200
});
// This event becomes your retention metricInterpreting Your Retention Cohort
Once Mixpanel builds the retention table, you're reading a cohort matrix: users grouped by signup date, retention measured by days or weeks after.
Step 1: Read the retention matrix
Each row is a cohort ("Signed up Week 1"). Each column is a time period (Day 0, Day 1, Day 7, etc.). The cell shows the percentage of that cohort that returned. A row of [100%, 45%, 32%, 28%] means 45% came back on Day 1, 32% on Day 7.
// Example: parsing retention matrix
const retentionData = {
'cohort_week_1': {
'day_0': 100,
'day_1': 45,
'day_7': 32,
'day_30': 28
},
'cohort_week_2': {
'day_0': 100,
'day_1': 48,
'day_7': 35,
'day_30': 30
}
};
const weekOneDay7 = retentionData.cohort_week_1.day_7; // 32%Step 2: Spot trends across cohorts
Compare rows. If older cohorts have lower Week 1 retention than newer ones, you've improved onboarding. If retention drops off the cliff at Day 7, users might be completing a trial and churning.
// Calculate average retention across cohorts
const cohorts = [
{ week: 1, day_7_retention: 32 },
{ week: 2, day_7_retention: 35 },
{ week: 3, day_7_retention: 38 }
];
const avgDay7 = cohorts.reduce((sum, c) => sum + c.day_7_retention, 0) / cohorts.length;
console.log(`Average Day 7 Retention: ${avgDay7.toFixed(1)}%`); // 35%
// Spot improvement trend
const improving = cohorts[2].day_7_retention > cohorts[0].day_7_retention;Exporting Retention Data for Analysis
Sometimes you need retention numbers outside Mixpanel—for dashboards, reports, or deeper analysis.
Step 1: Use the Mixpanel Data Export API
Mixpanel's REST API lets you fetch retention data programmatically. The Retention endpoint returns cohort retention percentages in JSON. You'll need your project token and API secret.
// Fetch retention data from Mixpanel API
const projectToken = 'your-project-token';
const apiSecret = 'your-api-secret';
const startDate = '2025-01-01';
const endDate = '2025-03-26';
const retentionUrl = `https://data.mixpanel.com/api/2.0/retention?from_date=${startDate}&to_date=${endDate}&unit=week&on=`;
const response = await fetch(retentionUrl, {
headers: {
'Authorization': `Basic ${btoa(apiSecret + ':')}`
}
});
const retentionData = await response.json();
console.log(retentionData.data);Step 2: Parse and store the response
The API returns raw percentages. Convert them to decimals or absolute user counts for analysis. Store in your database or send to a BI tool like Looker or Tableau.
// Parse and normalize retention response
function parseRetention(apiResponse) {
const normalized = {};
apiResponse.data.forEach(cohort => {
const cohortDate = cohort[0];
const retentionValues = cohort.slice(1);
normalized[cohortDate] = {
day_0: 100,
day_1: retentionValues[0] || 0,
day_7: retentionValues[1] || 0,
day_30: retentionValues[2] || 0
};
});
return normalized;
}
const cleanData = parseRetention(retentionData);
// Store in database or send to analytics toolCommon Pitfalls
- Forgetting that Day 0 is always 100%—it's the cohort definition, not a conversion. Retention starts at Day 1.
- Mixing up retention with repeat rate. Retention = percent who came back at least once. Repeat rate = average times they came back.
- Choosing a retention event that's too rare ("Upgraded Plan") when you should track daily engagement ("Logged In").
- Not accounting for cohort size. A 95% retention rate for 3 users means almost nothing; 80% for 1,000 users is real.
Wrapping Up
You now have retention data—use it. Compare cohorts, track changes week-to-week, and adjust onboarding or core features if retention drops. If you want to track and analyze retention automatically across all your tools, Product Analyst can help.