Skip to main content
GET
/
api
/
query
/
retention
Retention
curl --request GET \
  --url https://mixpanel.com/api/query/retention
{
  "data": {
    "counts": [
      {}
    ],
    "first": 123
  }
}

​
Query Retention

Retrieve retention metrics including birth retention, compounded retention, and frequency data.

​
Query Retention Report

​
project_id
integer
required
Your Mixpanel project ID
​
workspace_id
integer
The workspace ID
​
from_date
string
required
Start date in YYYY-MM-DD format
​
to_date
string
required
End date in YYYY-MM-DD format
​
retention_type
string
Type of retention analysis.Options: birth (first time retention) or compounded (recurring retention)Default: birth
​
born_event
string
The first event a user must do to be counted in a birth retention cohort. Required when retention_type is birth.
​
event
string
The event to generate returning counts for. Applies to both birth and compounded retention.
​
born_where
string
Expression to filter born_events by
​
where
string
Expression to filter return events by
​
interval
integer
The number of units per bucketed interval. Default is 1.
​
interval_count
integer
The number of individual buckets/intervals returned. Default is 1.
​
unit
string
The interval unit.Options: day, week, monthDefault: day
​
unbounded_retention
boolean
Accumulate retention values from right to left. When true, day N equals users who retained on day N and any day after.Default: false
​
on
string
Property to segment retention by
​
limit
integer
Maximum number of property values to return when segmenting

​
Example Request

curl "https://mixpanel.com/api/query/retention?project_id=123&from_date=2024-01-01&to_date=2024-01-31&retention_type=birth&born_event=Signed%20Up&event=App%20Open" \
  -u SERVICE_ACCOUNT_USERNAME:SERVICE_ACCOUNT_SECRET

​
Response

​
data
object
Retention data with dates as keys
{
  "2024-01-01": {
    "counts": [50, 45, 42, 40, 38],
    "first": 50
  },
  "2024-01-02": {
    "counts": [75, 68, 63, 59, 55],
    "first": 75
  },
  "2024-01-03": {
    "counts": [60, 55, 51, 48, 45],
    "first": 60
  }
}

​
Use Cases

​
Calculate Retention Rates

import requests
from requests.auth import HTTPBasicAuth

def calculate_retention_rates(project_id):
    """Calculate Day 1, Day 7, Day 30 retention rates"""
    
    response = requests.get(
        'https://mixpanel.com/api/query/retention',
        auth=HTTPBasicAuth('USERNAME', 'SECRET'),
        params={
            'project_id': project_id,
            'from_date': '2024-01-01',
            'to_date': '2024-01-31',
            'retention_type': 'birth',
            'born_event': 'Signed Up',
            'event': 'App Open',
            'interval_count': 30
        }
    )
    
    data = response.json()
    
    # Calculate average retention rates
    day1_rates = []
    day7_rates = []
    day30_rates = []
    
    for date, cohort in data.items():
        first = cohort['first']
        counts = cohort['counts']
        
        if len(counts) > 0:
            day1_rates.append(counts[0] / first)
        if len(counts) > 6:
            day7_rates.append(counts[6] / first)
        if len(counts) > 29:
            day30_rates.append(counts[29] / first)
    
    print(f"Day 1 Retention: {sum(day1_rates)/len(day1_rates):.1%}")
    print(f"Day 7 Retention: {sum(day7_rates)/len(day7_rates):.1%}")
    print(f"Day 30 Retention: {sum(day30_rates)/len(day30_rates):.1%}")

calculate_retention_rates(123)

Build docs developers (and LLMs) love

Get started for freeTalk to us