Rate Limits

Understanding API rate limits and best practices

Rate Limits

Mixpanel enforces rate limits on API endpoints to ensure system stability and fair usage across all customers.

Rate Limits by API

Ingestion API

Import Events · /import

Rate Limit: No hard limit, but 429 errors may be returned during high load

Best Practice: Implement exponential backoff on 429 errors

Track Events · /track

Rate Limit: No hard limit for reasonable usage

Recommendation: Batch events when possible (up to 2000 events per request)

Query API

Query Endpoints · All query endpoints

Rate Limit: 60 queries per hour, 5 concurrent queries maximum

Per Second: 3 queries per second

Status Code: 429 Too Many Requests

Applies to:

• /api/query/insights
• /api/query/funnels
• /api/query/retention
• /api/query/segmentation
• /api/query/cohorts
• /api/query/engage

Export API

Raw Export · /export

Rate Limit: 60 queries per hour, 3 queries per second, 100 concurrent queries maximum

Status Code: 429 Too Many Requests

Management APIs

Annotations, Schemas, Service Accounts · Management endpoints

Rate Limit: Standard HTTP rate limiting applies

Recommendation: Space out requests, avoid burst traffic

Request Limits

Ingestion Payload Limits

Endpoint	Max Payload Size	Max Events per Request
/import	2 MB	2000 events
/track	2 MB	2000 events
/engage	2 MB	2000 profile updates
/groups	2 MB	2000 group updates

Query Result Limits

Endpoint	Default Limit	Max Limit
/export	All events	100,000 events (with limit param)
/engage	1000 profiles	10,000 profiles
/segmentation (on parameter)	60 values	10,000 values

Handling Rate Limits

Detecting Rate Limit Errors

When you exceed rate limits, Mixpanel returns a 429 Too Many Requests response:

Response Example

{
  "code": 429,
  "error": "Project exceeded rate limits. Please retry the request with exponential backoff.",
  "status": "Too Many Requests"
}

Implementing Exponential Backoff

Python

import time
import requests

def import_with_backoff(events, max_retries=5):
    base_delay = 1  # Start with 1 second
    
    for attempt in range(max_retries):
        response = requests.post(
            'https://api.mixpanel.com/import',
            auth=('SERVICE_ACCOUNT', 'SECRET'),
            params={'project_id': 'PROJECT_ID', 'strict': '1'},
            json=events
        )
        
        if response.status_code == 200:
            return response.json()
        elif response.status_code == 429:
            if attempt < max_retries - 1:
                delay = base_delay * (2 ** attempt)  # Exponential backoff
                print(f"Rate limited. Retrying in {delay} seconds...")
                time.sleep(delay)
            else:
                raise Exception("Max retries exceeded")
        else:
            response.raise_for_status()

Best Practices

Batch Your Requests

Instead of sending individual events, batch them into arrays of up to 2000 events per request. This significantly reduces the number of API calls.

# Good: Batched
events = [event1, event2, event3, ...] # Up to 2000
response = requests.post(url, json=events)

# Bad: Individual
for event in events:
    response = requests.post(url, json=[event])

Implement Retry Logic

Always implement exponential backoff retry logic for 429 errors. Start with a 1-second delay and double it with each retry.

Cache Query Results

If you’re querying the same data frequently, cache the results on your side instead of making repeated API calls.

Use Webhooks for Real-time Data

For real-time updates, consider using Mixpanel’s webhook features instead of polling the Query API.

Compress Payloads

Use gzip compression for large payloads to reduce transfer time and stay within size limits:

import gzip
import json

compressed = gzip.compress(json.dumps(events).encode())
response = requests.post(
    url,
    data=compressed,
    headers={'Content-Encoding': 'gzip'}
)

Monitor Your Usage

Track your API usage to identify patterns and optimize before hitting rate limits.

Rate Limit Headers

Mixpanel may include rate limit information in response headers (implementation varies by endpoint):

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1609459200

Not all endpoints currently return rate limit headers. Use 429 status codes as the primary indicator.

Increasing Rate Limits

If you have a legitimate need for higher rate limits:

1. Contact Mixpanel Support
2. Describe your use case
3. Provide expected traffic patterns
4. Enterprise customers may have higher default limits

Rate limit increases are evaluated on a case-by-case basis and are not guaranteed.

Common Scenarios

High-Volume Event Ingestion

Problem: Sending millions of events per day

Solution:

• Batch events in groups of 2000
• Use multiple threads/workers with proper backoff
• Consider using Data Pipelines for bulk imports

Frequent Dashboard Updates

Problem: Polling Query API every minute for dashboard data

Solution:

• Cache results and refresh less frequently
• Use longer time windows to reduce query complexity
• Consider using Mixpanel’s embedding features

Bulk Data Export

Problem: Exporting large date ranges frequently

Solution:

• Use Data Pipelines for scheduled exports
• Limit export date ranges to reduce query time
• Export during off-peak hours