> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/mixpanel/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Retention

> Query retention and frequency data

# Query Retention

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

## Query Retention Report

<ParamField query="project_id" type="integer" required>
  Your Mixpanel project ID
</ParamField>

<ParamField query="workspace_id" type="integer">
  The workspace ID
</ParamField>

<ParamField query="from_date" type="string" required>
  Start date in `YYYY-MM-DD` format
</ParamField>

<ParamField query="to_date" type="string" required>
  End date in `YYYY-MM-DD` format
</ParamField>

<ParamField query="retention_type" type="string">
  Type of retention analysis.

  Options: `birth` (first time retention) or `compounded` (recurring retention)

  Default: `birth`
</ParamField>

<ParamField query="born_event" type="string">
  The first event a user must do to be counted in a birth retention cohort. Required when `retention_type` is `birth`.
</ParamField>

<ParamField query="event" type="string">
  The event to generate returning counts for. Applies to both birth and compounded retention.
</ParamField>

<ParamField query="born_where" type="string">
  Expression to filter born\_events by
</ParamField>

<ParamField query="where" type="string">
  Expression to filter return events by
</ParamField>

<ParamField query="interval" type="integer">
  The number of units per bucketed interval. Default is `1`.
</ParamField>

<ParamField query="interval_count" type="integer">
  The number of individual buckets/intervals returned. Default is `1`.
</ParamField>

<ParamField query="unit" type="string">
  The interval unit.

  Options: `day`, `week`, `month`

  Default: `day`
</ParamField>

<ParamField query="unbounded_retention" type="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`
</ParamField>

<ParamField query="on" type="string">
  Property to segment retention by
</ParamField>

<ParamField query="limit" type="integer">
  Maximum number of property values to return when segmenting
</ParamField>

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  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
  ```

  ```python Python theme={null}
  import requests
  from requests.auth import HTTPBasicAuth

  response = requests.get(
      'https://mixpanel.com/api/query/retention',
      auth=HTTPBasicAuth('SERVICE_ACCOUNT_USERNAME', 'SERVICE_ACCOUNT_SECRET'),
      params={
          'project_id': 123,
          'from_date': '2024-01-01',
          'to_date': '2024-01-31',
          'retention_type': 'birth',
          'born_event': 'Signed Up',
          'event': 'App Open',
          'unit': 'day',
          'interval_count': 30
      }
  )

  data = response.json()
  print(data)
  ```
</CodeGroup>

### Response

<ResponseField name="data" type="object">
  Retention data with dates as keys

  <Expandable title="data[date]">
    <ResponseField name="counts" type="array">
      Array of retention counts for each interval
    </ResponseField>

    <ResponseField name="first" type="integer">
      Number of users in the cohort
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```json 200 Success theme={null}
  {
    "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
    }
  }
  ```
</CodeGroup>

## Use Cases

### Calculate Retention Rates

<CodeGroup>
  ```python Python theme={null}
  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)
  ```
</CodeGroup>