Skip to main content
GET
/
api
/
query
/
funnels
Funnels
curl --request GET \
  --url https://mixpanel.com/api/query/funnels
{
  "meta": {
    "dates": [
      {}
    ]
  },
  "data": {
    "steps": [
      {
        "count": 123,
        "goal": "<string>",
        "step_conv_ratio": 123,
        "overall_conv_ratio": 123,
        "avg_time": 123,
        "avg_time_from_start": 123
      }
    ],
    "analysis": {
      "completion": 123,
      "starting_amount": 123,
      "steps": 123,
      "worst": 123
    }
  }
}

​
Query Funnels

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

​
Query Saved Funnel

​
project_id
integer
required
Your Mixpanel project ID
​
workspace_id
integer
The workspace ID
​
funnel_id
integer
required
The ID of the funnel you wish to query
​
from_date
string
required
Start date in YYYY-MM-DD format
​
to_date
string
required
End date in YYYY-MM-DD format
​
length
integer
The number of units (defined by length_unit) each user has to complete the funnel. May not be greater than 90 days.
​
length_unit
string
The unit applied to the length parameter.Options: second, minute, hour, dayDefault: Value saved in the UI for this funnel
​
interval
integer
The number of days you want each bucket to contain. Default is 1.
​
unit
string
Alternate way of specifying interval.Options: day, week, month
​
on
string
Property to segment the funnel by (e.g., properties["$browser"])
​
where
string
Expression to filter events. See segmentation expressions
​
limit
integer
Return the top property values. Defaults to 255, maximum 10,000. Only applies when on is specified.

​
Example Request

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

​
Response

​
meta
object
Metadata about the funnel query
​
data
object
Funnel data for each date, with dates as keys
{
  "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
      }
    }
  }
}

​
List Saved Funnels

Get a list of all funnels in your project.

​
Request

​
project_id
integer
required
Your Mixpanel project ID
​
workspace_id
integer
The workspace ID

​
Example

curl "https://mixpanel.com/api/query/funnels/list?project_id=123" \
  -u SERVICE_ACCOUNT_USERNAME:SERVICE_ACCOUNT_SECRET

​
Response

[
  {
    "funnel_id": 7509,
    "name": "Signup funnel"
  },
  {
    "funnel_id": 9070,
    "name": "Funnel tutorial"
  }
]

​
Use Cases

​
Monitor Conversion Rates

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)

​
Alert on Drop-offs

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)

Build docs developers (and LLMs) love

Get started for freeTalk to us