Set up Mixpanel with an AI agent

name: mixpanel
description: Use when implementing product analytics, tracking user events and
  behaviors, building reports and dashboards, running experiments, managing
  feature flags, or querying event data via APIs. Reach for this skill when
  working with event-based analytics, user segmentation, funnel analysis,
  retention metrics, or integrating Mixpanel with data warehouses and
  third-party tools.
metadata:
  mintlify-proj: mixpanel
  version: "1.0"

Mixpanel Skill

Product Summary

Mixpanel is an event-based product analytics platform that tracks user interactions, analyzes behavioral data, and powers decision-making through interactive reports. Use Mixpanel to understand how users engage with your product by tracking events (actions), enriching them with properties (context), and analyzing them across user profiles and cohorts.

Key files and concepts:

• Project token: Found in project settings; required for all SDK initialization and API calls
• Events: Core data unit representing user actions (e.g., "Sign Up", "Purchase")
• Properties: Metadata attached to events (event properties) or users (user profile properties)
• Distinct ID: Unique user identifier used to join events with user profiles
• Data residency: Projects can be US (default), EU (api-eu.mixpanel.com), or India (api-in.mixpanel.com)

Primary documentation: https://docs.mixpanel.com

Core APIs:

• Ingestion API: Send events, user profiles, and group profiles
• Query API: Retrieve calculated data (Insights, Funnels, Retention)
• Raw Data Export API: Download raw event data
• Data Pipelines API: Export to data warehouses

When to Use

Reach for this skill when:

• Implementing tracking: Setting up SDKs (JavaScript, Python, Node, mobile, etc.) or HTTP API to send events
• Building reports: Creating Insights, Funnels, Retention, or Flow reports to analyze user behavior
• Segmenting users: Defining cohorts, applying filters, or using group analytics
• Running experiments: Setting up feature flags, A/B tests, or multivariate experiments
• Exporting data: Syncing cohorts to external tools, exporting to data warehouses, or querying via APIs
• Debugging data: Validating event structure, checking distinct_id consistency, or troubleshooting missing data
• Managing data governance: Defining tracking plans, enforcing data standards, or cleaning up events

Quick Reference

SDK Installation by Platform

Platform	Package Manager	Key Config
JavaScript	npm install mixpanel-browser	mixpanel.init("TOKEN", {track_pageview: true})
Python	pip install mixpanel	mp = Mixpanel("TOKEN")
Node.js	npm install mixpanel	Mixpanel.init("TOKEN")
React Native	npm install mixpanel-react-native	new Mixpanel("TOKEN")
Android	Gradle: com.mixpanel.android:mixpanel-android:7.+	MixpanelAPI.getInstance(context, "TOKEN")
iOS (Swift)	CocoaPods: pod 'Mixpanel-swift'	Mixpanel.initialize(token: "TOKEN")
Go	go get github.com/mixpanel/mixpanel-go	mixpanel.NewApiClient("TOKEN")
Java	Maven: com.mixpanel:mixpanel-java:1.4.4	new MixpanelAPI() with token
HTTP API	No install required	POST to /track or /import endpoints

Essential API Endpoints

Endpoint	Purpose	Auth
POST /track	Send events from client or server	Project token
POST /import	Batch import historical events	Project token (basic auth)
POST /engage	Set/update user profile properties	Project token
POST /groups	Set/update group profile properties	Project token
/api/2.0/export	Export raw event data	Service account or project secret
/api/query	Query Insights, Funnels, Retention	Service account
/flags	Get feature flag assignments	Project token

Common Event Tracking Pattern

# Server-side example (Python)
from mixpanel import Mixpanel

mp = Mixpanel("YOUR_TOKEN")

# Track an event with properties
mp.track(
    distinct_id="user_123",
    event_name="Purchase",
    properties={
        "amount": 99.99,
        "currency": "USD",
        "product_id": "SKU-456"
    }
)

# Set user profile properties
mp.people_set(
    distinct_id="user_123",
    properties={
        "$email": "user@example.com",
        "$name": "John Doe",
        "plan": "premium"
    }
)

Report Types and Use Cases

Report Type	Best For	Key Metric
Insights	Trends, compositions, aggregations	Total events, unique users, averages
Funnels	Conversion flows, drop-off analysis	Conversion rate, time to convert
Retention	User engagement over time	% retained, cohort retention curves
Flows	User journey paths	Most common sequences
Experiments	A/B testing, feature rollout	Statistical significance, variant performance

Decision Guidance

When to Use Client-Side vs Server-Side Tracking

Aspect	Client-Side	Server-Side
Reliability	Susceptible to ad-blockers (30-50% loss)	Reliable, not blocked
Use Case	Anonymous users, client-only interactions	Authenticated users, core business events
Data Consistency	Diverges across platforms	Consistent across all sources
Implementation	JavaScript, mobile SDKs	Python, Node, Go, Java, PHP
Recommendation	Supplement only	Primary method (Mixpanel recommends)

When to Use Different Report Types

Question	Report
How is my DAU/WAU/MAU trending?	Insights
What % of users complete my signup flow?	Funnels
Are users coming back after day 1?	Retention
What paths do users take to checkout?	Flows
Does variant A outperform variant B?	Experiments

Authentication Method Selection

Use Case	Method	Details
Client-side tracking	Project token	Embedded in SDK, no secrets exposed
Server-side tracking	Project token	Passed to SDK initialization
Query/Export APIs	Service account	Recommended for production; supports fine-grained permissions
Legacy integrations	Project secret	Deprecated; use service account instead

Workflow

1. Plan Your Tracking Strategy

• Define KPIs and business goals
• Map user flows to events and properties
• Create a tracking plan document (use Mixpanel templates for your vertical)
• Identify distinct_id strategy (email, user ID, device ID)
• Decide on data residency (US, EU, or India)

2. Install and Initialize Mixpanel

• Choose tracking method: client-side SDK, server-side SDK, or HTTP API
• Install the appropriate SDK for your platform
• Initialize with your project token (found in project settings)
• For EU/India projects, set the correct api_host parameter
• Enable optional features (session replay, heatmaps, autocapture) as needed

3. Implement Event Tracking

• Track core events at key user journey points (signup, purchase, feature use)
• Attach event properties for context (amount, category, platform, etc.)
• Use consistent distinct_id across all events for the same user
• For server-side: track authenticated user events; use device ID for anonymous users
• For client-side: use autocapture for page views; manually track custom events

4. Set Up User Profiles (Optional)

• Identify when to use user profiles (enrichment with demographic/account data)
• Set profile properties via people_set() or profile_set() API
• Use $set_once for immutable properties (signup date, first source)
• Keep profile properties in sync with your backend source of truth

5. Validate Data Quality

• Use Data Inspector to examine event payloads and verify structure
• Check that distinct_id is consistent across platforms
• Run count verification: compare event totals in Mixpanel vs your backend
• Look for duplicate profiles (sign of ID merge issues)
• Enable debug mode during development to catch ingestion errors

6. Build Reports and Analysis

• Create Insights report: select metric (event), measurement (unique users), filters, breakdowns
• Create Funnels: define steps, set conversion window, analyze drop-off
• Create Retention: define starting event and return event, measure cohort retention
• Save metrics and behaviors for reuse across reports
• Add to Boards for team visibility

7. Segment and Export

• Create cohorts based on event behavior or profile properties
• Use cohorts to filter reports or export to external tools (Braze, Segment, etc.)
• Set up Data Pipelines to sync events to data warehouse (Snowflake, BigQuery, etc.)
• Query via Query API for programmatic access to report data

8. Monitor and Iterate

• Set up alerts on key metrics for anomaly detection
• Review data governance: verify event naming, property consistency
• Audit tracking implementation quarterly; update tracking plan as product evolves
• Use Root Cause Analysis to investigate unexpected metric changes

Common Gotchas

• Distinct ID mismatch: If the same user gets different IDs across web/mobile/backend, Mixpanel creates duplicate profiles. Always use a single unifying ID (e.g., user_id) across all platforms.

• Events older than 5 days rejected: Client-side /track endpoint only accepts events from the last 5 days. Use /import endpoint for historical data backfills.

• Geolocation from server IP: Server-side tracking uses your server's IP for geolocation, not the user's. Pass ip property explicitly or use client-side tracking for accurate location.

• Profile properties are mutable: Unlike events (immutable), profile properties can be updated. Use $set_once for properties that should never change (e.g., signup date).

• Cohort sync limits: Dynamic cohort syncs are limited to 60 per project; static syncs are unlimited. Cohorts are capped at 10M users per sync.

• Ad-blocker impact: Client-side tracking loses 30-50% of events due to ad-blockers. Mitigate by using server-side tracking or setting up a proxy.

• Rate limits on imports: Bulk imports are rate-limited at scale. Use batching (up to 2000 events per request), compression (gzip), and exponential backoff for retries.

• Event property cardinality: High-cardinality properties (unique IDs, timestamps) can cause performance issues. Use bucketing or aggregation instead.

• Timezone handling: Events are stored in your project's timezone. Ensure consistent timezone handling across client and server.

• Feature flag persistence: Persisted variants are tied to distinct_id. Calling identify() with a new ID clears persisted data and triggers a fresh fetch.

Verification Checklist

Before submitting work, verify:

• Tracking implementation: Events are appearing in Data Inspector with correct structure and properties
• Distinct ID consistency: Same user has single distinct_id across all platforms (web, mobile, backend)
• Data residency: SDK is configured for correct region (US, EU, or India)
• Event counts: Event totals in Mixpanel match expected counts from backend logs
• User profiles: Profile properties are populated and match source system
• Report accuracy: Insights/Funnels/Retention metrics align with business expectations
• Cohort size: Cohorts have expected user counts; no unexpectedly empty cohorts
• API authentication: Service accounts have correct permissions for Query/Export APIs
• Data quality: No duplicate events (check $insert_id deduplication); no orphaned events without distinct_id
• Documentation: Tracking plan is updated; event/property naming follows conventions

Resources

Comprehensive navigation: https://docs.mixpanel.com/llms.txt

Critical documentation pages:

1. What is Mixpanel — Core concepts (events, users, properties)
2. Data Model — How events, profiles, and lookup tables join
3. Choosing the Right Tracking Method — Client-side vs server-side decision guide
4. Tracking Best Practices — Data validation and debugging
5. API Overview — All API endpoints and authentication methods

---

For additional documentation and navigation, see: https://docs.mixpanel.com/llms.txt