mixpanelyst

mixpanel_headless

⚠️ Pre-release Software: This package is under active development. APIs may change between versions before 1.0.

A complete programmable interface to Mixpanel analytics—Python library and CLI for discovery, querying, streaming, and entity management.

Why mixpanel_headless?

Mixpanel's web UI is powerful for interactive exploration, but programmatic access requires navigating multiple REST endpoints with different conventions. mixpanel_headless provides a unified interface: discover your schema, run analytics queries, stream data, and manage entities—all through consistent Python methods or CLI commands.

Core analytics—typed Insights engine queries (DAU/WAU/MAU, formulas, filters, breakdowns, cohort-scoped queries, period-over-period comparison, frequency analysis), typed funnel queries (ad-hoc steps, exclusions, conversion windows), typed retention queries (event pairs, custom buckets, alignment modes), typed flow queries (path analysis, direction controls, visualization modes), typed user profile queries (property filtering, sorting, parallel fetching, aggregate statistics), segmentation, saved reports—plus entity management (dashboards, reports, cohorts, feature flags, experiments), streaming data extraction, and session replay (discover, fetch, and analyze rrweb session recordings).

Installation

pip install mixpanel-headless

Requires Python 3.10+. Verify installation:

mp --version

Quick Start

1. Authenticate

Recommended: mp login

mp login
# Opens browser for PKCE (default region: us).
# Derives the account name from your /me org;
# auto-picks your project (or shows a picker when you have several).
mp session                    # Verify resolved state

mp login reads your environment first and picks the right auth path:

• MP_USERNAME + MP_SECRET set → service account (no browser, region auto-probes us → eu → in).
• MP_OAUTH_TOKEN set → static bearer (no browser, region auto-probes us → eu → in; the token is persisted inline to ~/.mp/config.toml).
• Neither → OAuth browser flow (region defaults to us; pass --region eu|in for other clusters).

Pass --region us|eu|in to set the region explicitly, --project ID to skip the project picker, or --name NAME to override the derived account name.

Service Account (scripts, CI/CD)

For unattended automation, set the four env vars and run any mp command:

export MP_USERNAME="sa_xxx"
export MP_SECRET="your-secret-here"
export MP_PROJECT_ID="12345"
export MP_REGION="us"
mp inspect events

Or persist the credentials to a named account so the secret lives on disk (mode 0o600) instead of every shell:

export MP_USERNAME="sa_xxx"
export MP_SECRET="your-secret-here"
mp login --service-account --name team
# `mp login --service-account` reads MP_USERNAME + MP_SECRET from env;
# both must be set or it errors. For explicit control over the username:
echo "$MP_SECRET" | mp account add team --type service_account \
    --username sa_xxx --project 12345 --region us --secret-stdin

Raw OAuth Bearer Token (CI / agents)

If a managed OAuth client (a Claude Code plugin, CI pipeline) hands you a pre-obtained access token, inject it via env vars without going through the browser flow:

export MP_OAUTH_TOKEN="<bearer-token>"
export MP_PROJECT_ID="12345"
export MP_REGION="us"  # or "eu", "in"

The full service-account env-var set (MP_USERNAME + MP_SECRET + MP_PROJECT_ID + MP_REGION) takes precedence when both sets are complete, so this is safe to add to a shell that already exports the service-account vars.

For users who want full control over the account name, region, and type at registration time:

# Register first, then run the PKCE flow
mp account add personal --type oauth_browser --region us
mp account login personal

mp login --name personal --region us is the one-line equivalent.

2. Explore Your Data

mp inspect events                      # List all events
mp inspect properties --event Purchase # Properties for an event
mp inspect funnels                     # Saved funnels

3. Run Analytics Queries

import mixpanel_headless as mp

ws = mp.Workspace()

# Typed insights query (recommended)
result = ws.query("Purchase", math="unique", group_by="country", last=30)
print(result.df)

# Or use the CLI for legacy query methods
mp query segmentation --event Purchase --from 2025-01-01 --to 2025-01-31 --on country

4. Stream Data (Python API)

import mixpanel_headless as mp

ws = mp.Workspace()
for event in ws.stream_events(from_date="2025-01-01", to_date="2025-01-31"):
    print(event["event"])

Python API

import mixpanel_headless as mp
from mixpanel_headless import Metric, Filter, Formula, GroupBy, RetentionEvent
from mixpanel_headless import TimeComparison, FrequencyBreakdown, FrequencyFilter

ws = mp.Workspace()

# Discover what's in your project
events = ws.events()
props = ws.properties("Purchase")
funnels = ws.funnels()
cohorts = ws.cohorts()

# Insights queries — typed, composable analytics
result = ws.query("Login")                            # simple event count
result = ws.query("Login", math="dau", last=90)       # DAU trend
result = ws.query("Purchase", math="total",             # revenue by country
    math_property="amount", group_by="country")
result = ws.query(                                     # conversion rate formula
    [Metric("Signup", math="unique"), Metric("Purchase", math="unique")],
    formula="(B / A) * 100",
    formula_label="Conversion Rate",
    unit="week",
)
result = ws.query("Purchase",                          # filtered with breakdown
    where=Filter.equals("country", "US"),
    group_by=GroupBy("amount", property_type="number", bucket_size=50),
)
print(result.df)  # pandas DataFrame

# Period-over-period comparison — compare against previous month
result = ws.query("Login", math="dau",
    time_comparison=TimeComparison.relative("month"), last=30)

# Frequency breakdown — segment by purchase frequency
result = ws.query("Login",
    group_by=FrequencyBreakdown(event="Purchase", bucket_max=10),
    last=30)

# New filter methods
result = ws.query("Purchase",
    where=[Filter.at_least("amount", 50), Filter.starts_with("email", "admin")])

# Typed funnel query — define steps inline
funnel = ws.query_funnel(
    ["Signup", "Add to Cart", "Purchase"],
    conversion_window=7,
    last=90,
)
print(funnel.overall_conversion_rate)  # e.g. 0.12

# Typed retention query — cohort retention with event pairs
retention = ws.query_retention(
    "Signup",
    "Login",
    retention_unit="week",
    last=90,
)
print(retention.df.head())  # cohort_date | bucket | count | rate

# Typed flow query — analyze user paths
from mixpanel_headless import FlowStep
flow_result = ws.query_flow("Purchase", forward=3, reverse=1)
print(flow_result.nodes_df.head())   # step | event | type | count
print(flow_result.top_transitions(5))

# User profile query — filter, sort, and aggregate profiles
result = ws.query_user(
    mode="profiles",
    where=Filter.equals("plan", "premium"),
    properties=["$email", "$name", "ltv"],
    sort_by="ltv",
    sort_order="descending",
    limit=50,
)
print(result.df)  # distinct_id | last_seen | email | name | ltv

# Aggregate count of matching profiles (aggregate is the default mode)
count = ws.query_user(where=Filter.is_set("$email"))
print(f"Users with email: {count.value}")

# Cohort-scoped queries — define cohorts inline, no UI needed
from mixpanel_headless import CohortCriteria, CohortDefinition, CohortBreakdown
power_users = CohortDefinition(
    Co