> ## 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.

# Funnels

> Query funnel analysis data

# Query Funnels

Retrieve funnel analysis data including conversion rates, step counts, and drop-off information.

## Query Saved Funnel

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

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

<ParamField query="funnel_id" type="integer" required>
  The ID of the funnel you wish to query
</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="length" type="integer">
  The number of units (defined by `length_unit`) each user has to complete the funnel. May not be greater than 90 days.
</ParamField>

<ParamField query="length_unit" type="string">
  The unit applied to the `length` parameter.

  Options: `second`, `minute`, `hour`, `day`

  Default: Value saved in the UI for this funnel
</ParamField>

<ParamField query="interval" type="integer">
  The number of days you want each bucket to contain. Default is `1`.
</ParamField>

<ParamField query="unit" type="string">
  Alternate way of specifying interval.

  Options: `day`, `week`, `month`
</ParamField>

<ParamField query="on" type="string">
  Property to segment the funnel by (e.g., `properties["$browser"]`)
</ParamField>

<ParamField query="where" type="string">
  Expression to filter events. See [segmentation expressions](ref:segmentation-expressions)
</ParamField>

<ParamField query="limit" type="integer">
  Return the top property values. Defaults to 255, maximum 10,000. Only applies when `on` is specified.
</ParamField>

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://mixpanel.com/api/query/funnels?project_id=123&funnel_id=789&from_date=2024-01-01&to_date=2024-01-31" \
    -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/funnels',
      auth=HTTPBasicAuth('SERVICE_ACCOUNT_USERNAME', 'SERVICE_ACCOUNT_SECRET'),
      params={
          'project_id': 123,
          'funnel_id': 789,
          'from_date': '2024-01-01',
          'to_date': '2024-01-31',
          'unit': 'week'
      }
  )

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

### Response

<ResponseField name="meta" type="object">
  Metadata about the funnel query

  <Expandable title="meta">
    <ResponseField name="dates" type="array">
      Array of date strings in `YYYY-MM-DD` format
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data" type="object">
  Funnel data for each date, with dates as keys

  <Expandable title="data[date]">
    <ResponseField name="steps" type="array">
      Array of step objects with conversion data

      <Expandable title="steps[]">
        <ResponseField name="count" type="integer">
          Number of conversions at this step
        </ResponseField>

        <ResponseField name="goal" type="string">
          The name of the event at this step
        </ResponseField>

        <ResponseField name="step_conv_ratio" type="number">
          Conversion rate from previous step
        </ResponseField>

        <ResponseField name="overall_conv_ratio" type="number">
          Conversion rate from start of funnel
        </ResponseField>

        <ResponseField name="avg_time" type="integer">
          Mean time to convert from previous step (null for step 0)
        </ResponseField>

        <ResponseField name="avg_time_from_start" type="integer">
          Time to convert from first step
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="analysis" type="object">
      Summary statistics

      <Expandable title="analysis">
        <ResponseField name="completion" type="integer">
          Count in final step
        </ResponseField>

        <ResponseField name="starting_amount" type="integer">
          Count in first step
        </ResponseField>

        <ResponseField name="steps" type="integer">
          Number of steps in funnel
        </ResponseField>

        <ResponseField name="worst" type="integer">
          Step with highest drop-off
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```json 200 Success theme={null}
  {
    "meta": {
      "dates": ["2016-09-12", "2016-09-19", "2016-09-26"]
    },
    "data": {
      "2016-09-12": {
        "steps": [
          {
            "count": 32688,
            "avg_time": 2,
            "avg_time_from_start": 5,
            "step_conv_ratio": 1,
            "goal": "App Open",
            "overall_conv_ratio": 1,
            "event": "App Open"
          },
          {
            "count": 20524,
            "avg_time": 133,
            "avg_time_from_start": 133,
            "step_conv_ratio": 0.627875673029858,
            "goal": "Game Played",
            "overall_conv_ratio": 0.627875673029858,
            "event": "Game Played"
          }
        ],
        "analysis": {
          "completion": 20524,
          "starting_amount": 32688,
          "steps": 2,
          "worst": 1
        }
      }
    }
  }
  ```
</CodeGroup>

***

## List Saved Funnels

Get a list of all funnels in your project.

### Request

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

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

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://mixpanel.com/api/query/funnels/list?project_id=123" \
    -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/funnels/list',
      auth=HTTPBasicAuth('SERVICE_ACCOUNT_USERNAME', 'SERVICE_ACCOUNT_SECRET'),
      params={'project_id': 123}
  )

  funnels = response.json()
  for funnel in funnels:
      print(f"{funnel['name']}: ID {funnel['funnel_id']}")
  ```
</CodeGroup>

### Response

<CodeGroup>
  ```json 200 Success theme={null}
  [
    {
      "funnel_id": 7509,
      "name": "Signup funnel"
    },
    {
      "funnel_id": 9070,
      "name": "Funnel tutorial"
    }
  ]
  ```
</CodeGroup>

## Use Cases

### Monitor Conversion Rates

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

  def monitor_conversion(project_id, funnel_id):
      """Monitor funnel conversion rates"""
      
      response = requests.get(
          'https://mixpanel.com/api/query/funnels',
          auth=HTTPBasicAuth('USERNAME', 'SECRET'),
          params={
              'project_id': project_id,
              'funnel_id': funnel_id,
              'from_date': '2024-01-01',
              'to_date': '2024-01-31'
          }
      )
      
      data = response.json()
      
      # Calculate average conversion rate
      total_conversions = []
      for date, date_data in data['data'].items():
          analysis = date_data['analysis']
          conv_rate = analysis['completion'] / analysis['starting_amount']
          total_conversions.append(conv_rate)
      
      avg_conversion = sum(total_conversions) / len(total_conversions)
      print(f"Average conversion rate: {avg_conversion:.2%}")
      
      # Identify worst performing step
      worst_step = date_data['analysis']['worst']
      print(f"Worst performing step: {worst_step}")

  monitor_conversion(123, 789)
  ```
</CodeGroup>

### Alert on Drop-offs

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

  def alert_on_dropoff(project_id, funnel_id, threshold=0.5):
      """Alert when funnel step conversion drops below threshold"""
      
      response = requests.get(
          'https://mixpanel.com/api/query/funnels',
          auth=HTTPBasicAuth('USERNAME', 'SECRET'),
          params={
              'project_id': project_id,
              'funnel_id': funnel_id,
              'from_date': '2024-01-01',
              'to_date': '2024-01-31'
          }
      )
      
      data = response.json()
      
      # Check most recent date
      latest_date = sorted(data['data'].keys())[-1]
      steps = data['data'][latest_date]['steps']
      
      alerts = []
      for i, step in enumerate(steps):
          if i > 0 and step['step_conv_ratio'] < threshold:
              alerts.append({
                  'step': i,
                  'goal': step['goal'],
                  'conversion': step['step_conv_ratio']
              })
      
      if alerts:
          print(f"⚠️ {len(alerts)} steps below {threshold:.0%} conversion:")
          for alert in alerts:
              print(f"  Step {alert['step']} ({alert['goal']}): {alert['conversion']:.1%}")
      else:
          print("✅ All steps above threshold")

  alert_on_dropoff(123, 789, threshold=0.6)
  ```
</CodeGroup>