Retention

Query retention and frequency data

GET /api/query/retention

Retention

cURL

curl --request GET \
  --url https://mixpanel.com/api/query/retention

200

{
  "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, month

Default: 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

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

Show data[date]

counts · array

Array of retention counts for each interval

first · integer

Number of users in the cohort

200 Success

{
  "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

Python

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)