CLI Commands¶
Complete reference for the mp command-line interface.
Explore on DeepWiki
🤖 CLI Command Reference →
Ask questions about specific commands, explore options, or get examples for your use case.
mp¶
Mixpanel data CLI - fetch, store, and query analytics data.
Usage:
Options:
-a, --account TEXT Account name to use (overrides default). \[env var:
MP_ACCOUNT]
-q, --quiet Suppress progress output.
-v, --verbose Enable debug output.
--version Show version and exit.
--install-completion Install completion for the current shell.
--show-completion Show completion for the current shell, to copy it or
customize the installation.
auth¶
Manage authentication and accounts.
Usage:
add¶
Add a new account to the configuration.
The secret can be provided via: - Interactive prompt (default, hidden input) - MP_SECRET environment variable (for CI/CD) - --secret-stdin flag to read from stdin
Examples:
mp auth add production -u myuser -p 12345
MP_SECRET=abc123 mp auth add production -u myuser -p 12345 # inline env var
echo "$SECRET" | mp auth add production -u myuser -p 12345 --secret-stdin
mp auth add staging -u myuser -p 12345 -r eu --default
Usage:
Options:
NAME Account name (identifier). \[required]
-u, --username TEXT Service account username.
-p, --project TEXT Project ID.
-r, --region TEXT Region: us, eu, or in. \[default: us]
-d, --default Set as default account.
-i, --interactive Prompt for all credentials.
--secret-stdin Read secret from stdin.
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
list¶
List all configured accounts.
Shows account name, username, project ID, region, and default status.
Examples:
mp auth list
mp auth list --format table
Usage:
Options:
remove¶
Remove an account from the configuration.
Deletes the account credentials from local config. Use --force to skip the confirmation prompt.
Examples:
mp auth remove staging
mp auth remove old_account --force
Usage:
Options:
NAME Account name to remove. \[required]
--force Skip confirmation prompt.
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
show¶
Show account details (secret is redacted).
Displays configuration for the named account or default if omitted.
Examples:
mp auth show
mp auth show production
mp auth show --format table
Usage:
Options:
[NAME] Account name (default if omitted).
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
switch¶
Set an account as the default.
The default account is used when --account is not specified.
Examples:
mp auth switch production
mp auth switch staging
Usage:
Options:
NAME Account name to set as default. \[required]
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
test¶
Test account credentials by pinging the API.
Verifies that the credentials are valid and can access the project.
Examples:
mp auth test
mp auth test production
Usage:
Options:
[NAME] Account name to test (default if omitted).
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
fetch¶
Fetch data from Mixpanel.
Usage:
events¶
Fetch events from Mixpanel into local storage.
Events are stored in a DuckDB table for SQL querying. A progress bar shows fetch progress (disable with --no-progress or --quiet).
Note: This is a long-running operation. For large date ranges, use --parallel for up to 10x faster exports.
Use --events to filter by event name (comma-separated list). Use --where for Mixpanel expression filters (e.g., 'properties["country"]=="US"'). Use --limit to cap the number of events returned (max 100000). Use --replace to drop and recreate an existing table. Use --append to add data to an existing table. Use --parallel/-p for faster parallel fetching (recommended for large date ranges). Use --chunk-days to configure days per chunk for parallel fetching (default: 7). Use --stdout to stream JSONL to stdout instead of storing locally. Use --raw with --stdout to output raw Mixpanel API format.
Output Structure (JSON):
{
"table": "events",
"rows": 15234,
"type": "events",
"duration_seconds": 12.5,
"date_range": ["2025-01-01", "2025-01-31"],
"fetched_at": "2025-01-15T10:30:00Z"
}
Parallel Output Structure (JSON):
{
"table": "events",
"total_rows": 15234,
"successful_batches": 5,
"failed_batches": 0,
"has_failures": false,
"duration_seconds": 2.5,
"fetched_at": "2025-01-15T10:30:00Z"
}
Examples:
mp fetch events --from 2025-01-01 --to 2025-01-31
mp fetch events signups --from 2025-01-01 --to 2025-01-31 --events "Sign Up"
mp fetch events --from 2025-01-01 --to 2025-01-31 --where 'properties["country"]=="US"'
mp fetch events --from 2025-01-01 --to 2025-01-31 --limit 10000
mp fetch events --from 2025-01-01 --to 2025-01-31 --replace
mp fetch events --from 2025-01-01 --to 2025-01-31 --append
mp fetch events --from 2025-01-01 --to 2025-01-31 --parallel
mp fetch events --from 2025-01-01 --to 2025-01-31 --parallel --chunk-days 1
mp fetch events --from 2025-01-01 --to 2025-01-31 --stdout
mp fetch events --from 2025-01-01 --to 2025-01-31 --stdout --raw | jq '.event'
jq Examples:
--jq '.rows' # Number of events fetched (sequential)
--jq '.total_rows' # Number of events fetched (parallel)
--jq '.duration_seconds | round' # Fetch duration in seconds
--jq '.date_range' # Date range fetched
Usage:
Options:
[NAME] Table name for storing events. Ignored with
--stdout.
--from TEXT Start date (YYYY-MM-DD).
--to TEXT End date (YYYY-MM-DD).
-e, --events TEXT Comma-separated event filter.
-w, --where TEXT Mixpanel filter expression.
-l, --limit INTEGER RANGE Maximum events to return (max 100000).
[1<=x<=100000]
--replace Replace existing table.
--append Append to existing table.
--no-progress Hide progress bar.
-p, --parallel Fetch in parallel using multiple threads. Faster
for large date ranges.
--workers INTEGER RANGE Number of parallel workers (default: 10). Only
applies with --parallel. \[x>=1]
--chunk-days INTEGER RANGE Days per chunk for parallel fetching (default:
7). Only applies with --parallel. \[default: 7;
1<=x<=100]
--stdout Stream to stdout as JSONL instead of storing.
--raw Output raw API format (only with --stdout).
--batch-size INTEGER RANGE Rows per commit. Controls memory/IO tradeoff.
(100-100000) \[default: 1000; 100<=x<=100000]
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
profiles¶
Fetch user profiles from Mixpanel into local storage.
Profiles are stored in a DuckDB table for SQL querying. A progress bar shows fetch progress (disable with --no-progress or --quiet).
Note: This can be a long-running operation for large profile sets. Use --parallel for up to 5x faster exports.
Use --where for Mixpanel expression filters on profile properties. Use --cohort to filter by cohort ID membership. Use --output-properties to select specific properties (reduces bandwidth). Use --distinct-id to fetch a single user's profile. Use --distinct-ids to fetch multiple specific users (repeatable flag). Use --group-id to fetch group profiles (e.g., companies) instead of users. Use --behaviors with --where to filter by user behavior (see --behaviors help for format). Use --as-of-timestamp to query historical profile state. Use --include-all-users with --cohort to include non-members with membership flag. Use --replace to drop and recreate an existing table. Use --append to add data to an existing table. Use --parallel/-p for faster parallel fetching (recommended for large profile sets). Use --stdout to stream JSONL to stdout instead of storing locally. Use --raw with --stdout to output raw Mixpanel API format.
Output Structure (JSON - Sequential):
{
"table": "profiles",
"rows": 5000,
"type": "profiles",
"duration_seconds": 8.2,
"date_range": null,
"fetched_at": "2025-01-15T10:30:00Z"
}
Output Structure (JSON - Parallel):
{
"table": "profiles",
"total_rows": 5000,
"successful_pages": 5,
"failed_pages": 0,
"failed_page_indices": [],
"duration_seconds": 1.8,
"fetched_at": "2025-01-15T10:30:00Z"
}
Examples:
mp fetch profiles
mp fetch profiles users --replace
mp fetch profiles users --append
mp fetch profiles --parallel
mp fetch profiles --parallel --workers 3
mp fetch profiles --where 'properties["plan"]=="premium"'
mp fetch profiles --cohort 12345
mp fetch profiles --output-properties '$email,$name,plan'
mp fetch profiles --distinct-id user_123
mp fetch profiles --distinct-ids user_1 --distinct-ids user_2
mp fetch profiles --group-id companies
mp fetch profiles --behaviors '[{"window":"30d","name":"buyers","event_selectors":[{"event":"Purchase"}]}]' --where '(behaviors["buyers"] > 0)'
mp fetch profiles --as-of-timestamp 1704067200
mp fetch profiles --cohort 12345 --include-all-users
mp fetch profiles --stdout
mp fetch profiles --stdout --raw
jq Examples:
--jq '.rows' # Number of profiles fetched (sequential)
--jq '.total_rows' # Number of profiles fetched (parallel)
--jq '.table' # Table name created
--jq '.duration_seconds | round' # Fetch duration in seconds
Usage:
Options:
[NAME] Table name for storing profiles. Ignored with
--stdout.
-w, --where TEXT Mixpanel filter expression.
-c, --cohort TEXT Filter by cohort ID.
-o, --output-properties TEXT Comma-separated properties to include.
--replace Replace existing table.
--append Append to existing table.
--no-progress Hide progress bar.
--stdout Stream to stdout as JSONL instead of storing.
--raw Output raw API format (only with --stdout).
--batch-size INTEGER RANGE Rows per commit. Controls memory/IO tradeoff.
(100-100000) \[default: 1000; 100<=x<=100000]
--distinct-id TEXT Fetch a specific user by distinct_id. Mutually
exclusive with --distinct-ids.
--distinct-ids TEXT Fetch specific users by distinct_id (can be
repeated). Mutually exclusive with --distinct-
id.
-g, --group-id TEXT Fetch group profiles (e.g., 'companies')
instead of user profiles.
--behaviors TEXT Behavioral filter as JSON array. Each behavior
needs: "window" (e.g., "30d"), "name"
(identifier), and "event_selectors" (array
with {"event":"Name"}). Use with --where to
filter by behavior count, e.g., --where
'(behaviors["name"] > 0)'. Example: '[{"window
":"30d","name":"buyers","event_selectors":[{"e
vent":"Purchase"}]}]'. Mutually exclusive with
--cohort.
--as-of-timestamp INTEGER Query profile state at a specific Unix
timestamp (must be in the past).
--include-all-users Include all users and mark cohort membership.
Requires --cohort.
-p, --parallel Fetch in parallel using multiple threads. Up
to 5x faster for large exports.
--workers INTEGER Number of parallel workers (default: 5, max:
5). Only applies with --parallel.
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
inspect¶
Inspect schema and local database.
Usage:
bookmarks¶
List saved reports (bookmarks) in Mixpanel project.
Calls the Mixpanel API to retrieve saved report definitions. Use the bookmark ID with 'mp query saved-report' or 'mp query flows'.
Output Structure (JSON):
[
{"id": 98765, "name": "Weekly KPIs", "type": "insights", "modified": "2024-01-15T10:30:00"},
{"id": 98766, "name": "Conversion Funnel", "type": "funnels", "modified": "2024-01-14T15:45:00"},
{"id": 98767, "name": "User Retention", "type": "retention", "modified": "2024-01-13T09:20:00"}
]
Examples:
mp inspect bookmarks
mp inspect bookmarks --type insights
mp inspect bookmarks --type funnels --format table
jq Examples:
--jq '[.[] | select(.type == "insights")]' # Get bookmarks by type
--jq '[.[].id]' # Get bookmark IDs only
--jq 'sort_by(.modified) | reverse' # Sort by modified date (newest first)
--jq '.[] | select(.name | test("KPI"; "i"))' # Find bookmark by name
Usage:
Options:
-t, --type TEXT Filter by type: insights, funnels, retention, flows,
launch-analysis.
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
breakdown¶
Show event distribution in a table.
Analyzes event counts, unique users, date ranges, and percentages for each event type. Requires event_name, event_time, distinct_id columns.
Output Structure (JSON):
{
"table": "events",
"total_events": 125000,
"total_users": 8500,
"date_range": ["2024-01-01T00:00:00", "2024-01-31T23:59:59"],
"events": [
{
"event_name": "Page View",
"count": 75000,
"unique_users": 8200,
"first_seen": "2024-01-01T00:05:00",
"last_seen": "2024-01-31T23:55:00",
"pct_of_total": 60.0
},
{
"event_name": "Purchase",
"count": 5000,
"unique_users": 2100,
"first_seen": "2024-01-01T08:30:00",
"last_seen": "2024-01-31T22:15:00",
"pct_of_total": 4.0
}
]
}
Examples:
mp inspect breakdown -t events
mp inspect breakdown -t events --format json
jq Examples:
--jq '.events | sort_by(.count) | reverse | [.[].event_name]' # Event names sorted by count
--jq '.events | [.[] | select(.pct_of_total > 10)]' # Events with more than 10%
--jq '.total_events' # Get total event count
--jq '.events | max_by(.unique_users)' # Event with most unique users
Usage:
Options:
-t, --table TEXT Table name. \[required]
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
cohorts¶
List saved cohorts in Mixpanel project.
Calls the Mixpanel API to retrieve saved cohort definitions. Shows cohort ID, name, user count, and description.
Output Structure (JSON):
[
{"id": 1001, "name": "Power Users", "count": 5420, "description": "Users with 10+ sessions"},
{"id": 1002, "name": "Trial Users", "count": 892, "description": "Active trial accounts"},
{"id": 1003, "name": "Churned", "count": 2341, "description": "No activity in 30 days"}
]
Examples:
mp inspect cohorts
mp inspect cohorts --format table
jq Examples:
--jq '[.[] | select(.count > 1000)]' # Cohorts with more than 1000 users
--jq '[.[].name]' # Get cohort names only
--jq 'sort_by(.count) | reverse' # Sort by user count descending
--jq '.[] | select(.name == "Power Users")' # Find cohort by name
Usage:
Options:
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
column¶
Show detailed statistics for a single column.
Performs deep analysis including null rates, cardinality, top values, and numeric statistics. Supports JSON path expressions like "properties->>'$.country'" for analyzing JSON columns.
Output Structure (JSON):
{
"table": "events",
"column": "properties->>'$.country'",
"dtype": "VARCHAR",
"count": 120000,
"null_count": 5000,
"null_pct": 4.0,
"unique_count": 45,
"unique_pct": 0.04,
"top_values": [["US", 45000], ["UK", 22000], ["DE", 15000]],
"min": null,
"max": null,
"mean": null,
"std": null
}
Examples:
mp inspect column -t events -c event_name
mp inspect column -t events -c "properties->>'$.country'"
mp inspect column -t events -c distinct_id --top 20
jq Examples:
--jq '.top_values' # Get top values only
--jq '.null_pct' # Get null percentage
--jq '.unique_count' # Get unique count
--jq '.top_values | map(.[0])' # Get top value names only
Usage:
Options:
-t, --table TEXT Table name. \[required]
-c, --column TEXT Column name or expression. \[required]
--top INTEGER Number of top values to show. \[default: 10]
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
coverage¶
Show property coverage statistics from Mixpanel.
Uses JQL to count how often each property is defined (non-null) vs undefined. Useful for data quality assessment.
Output Structure (JSON):
{
"event": "Purchase",
"from_date": "2024-01-01",
"to_date": "2024-01-31",
"total_events": 5000,
"coverage": [
{"property": "amount", "defined_count": 5000, "null_count": 0, "coverage_percentage": 100.0},
{"property": "coupon_code", "defined_count": 1250, "null_count": 3750, "coverage_percentage": 25.0},
{"property": "referrer", "defined_count": 4500, "null_count": 500, "coverage_percentage": 90.0}
]
}
Examples:
mp inspect coverage -e Purchase -p coupon_code,referrer --from 2024-01-01 --to 2024-01-31
jq Examples:
--jq '.coverage | [.[] | select(.coverage_percentage < 50)]' # Properties with low coverage
--jq '.coverage | [.[] | select(.coverage_percentage == 100)]' # Fully covered properties
--jq '.coverage | [.[].property]' # Get property names only
--jq '.coverage | sort_by(.coverage_percentage)' # Sort by coverage percentage
Usage:
Options:
-e, --event TEXT Event name to analyze. \[required]
-p, --properties TEXT Comma-separated property names to check. \[required]
--from TEXT Start date (YYYY-MM-DD). \[required]
--to TEXT End date (YYYY-MM-DD). \[required]
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format
json or jsonl).
daily¶
Show daily event counts from Mixpanel.
Uses JQL to count events by day. Optionally filter to specific events. Useful for understanding activity trends over time.
Output Structure (JSON):
{
"from_date": "2024-01-01",
"to_date": "2024-01-07",
"events": ["Purchase", "Signup"],
"counts": [
{"date": "2024-01-01", "event": "Purchase", "count": 150},
{"date": "2024-01-01", "event": "Signup", "count": 45},
{"date": "2024-01-02", "event": "Purchase", "count": 175},
{"date": "2024-01-02", "event": "Signup", "count": 52}
]
}
Examples:
mp inspect daily --from 2024-01-01 --to 2024-01-07
mp inspect daily --from 2024-01-01 --to 2024-01-07 -e Purchase,Signup
jq Examples:
--jq '.counts | [.[] | select(.event == "Purchase")] | map(.count) | add' # Total for one event
--jq '.counts | [.[] | select(.date == "2024-01-01")]' # Counts for specific date
--jq '.counts | [.[].date] | unique' # Get all dates
--jq '.counts | group_by(.date) | [.[] | {date: .[0].date, total: map(.count) | add}]' # Daily totals
Usage:
Options:
--from TEXT Start date (YYYY-MM-DD). \[required]
--to TEXT End date (YYYY-MM-DD). \[required]
-e, --events TEXT Comma-separated event names (or all if omitted).
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
distribution¶
Show property value distribution from Mixpanel.
Uses JQL to count occurrences of each value for a property, showing counts and percentages sorted by frequency. Useful for understanding what values a property contains before writing queries.
Output Structure (JSON):
{
"event": "Purchase",
"property_name": "country",
"from_date": "2024-01-01",
"to_date": "2024-01-31",
"total_count": 50000,
"values": [
{"value": "US", "count": 25000, "percentage": 50.0},
{"value": "UK", "count": 10000, "percentage": 20.0},
{"value": "DE", "count": 7500, "percentage": 15.0}
]
}
Examples:
mp inspect distribution -e Purchase -p country --from 2024-01-01 --to 2024-01-31
mp inspect distribution -e Signup -p referrer --from 2024-01-01 --to 2024-01-31 --limit 10
jq Examples:
--jq '.values | [.[].value]' # Get values only
--jq '.values | [.[] | select(.percentage > 10)]' # Values with more than 10%
--jq '.total_count' # Get total count
--jq '.values[0]' # Get top value
Usage:
Options:
-e, --event TEXT Event name to analyze. \[required]
-p, --property TEXT Property name to get distribution for. \[required]
--from TEXT Start date (YYYY-MM-DD). \[required]
--to TEXT End date (YYYY-MM-DD). \[required]
-l, --limit INTEGER Maximum values to return. \[default: 20]
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
drop¶
Drop a table from the local database.
Permanently removes a table and all its data. Use --force to skip the confirmation prompt. Commonly used before re-fetching data.
Output Structure (JSON):
{"dropped": "old_events"}
Examples:
mp inspect drop -t old_events
mp inspect drop -t events --force
jq Examples:
--jq '.dropped' # Get dropped table name
Usage:
Options:
-t, --table TEXT Table name to drop. \[required]
--force Skip confirmation prompt.
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
drop-all¶
Drop all tables from the local database.
Permanently removes all tables and their data. Use --type to filter by table type. Use --force to skip the confirmation prompt.
Output Structure (JSON):
{"dropped_count": 3}
# With type filter:
{"dropped_count": 2, "type_filter": "events"}
Examples:
mp inspect drop-all --force
mp inspect drop-all --type events --force
mp inspect drop-all -t profiles --force
jq Examples:
--jq '.dropped_count' # Get count of dropped tables
--jq '.dropped_count > 0' # Check if any tables were dropped
Usage:
Options:
-t, --type TEXT Only drop tables of this type: events or profiles.
--force Skip confirmation prompt.
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
engagement¶
Show user engagement distribution from Mixpanel.
Uses JQL to bucket users by their event count, showing how many users performed N events. Useful for understanding user engagement levels.
Output Structure (JSON):
{
"from_date": "2024-01-01",
"to_date": "2024-01-31",
"events": null,
"total_users": 8500,
"buckets": [
{"bucket_min": 1, "bucket_label": "1", "user_count": 2500, "percentage": 29.4},
{"bucket_min": 2, "bucket_label": "2-5", "user_count": 3200, "percentage": 37.6},
{"bucket_min": 6, "bucket_label": "6-10", "user_count": 1800, "percentage": 21.2},
{"bucket_min": 11, "bucket_label": "11+", "user_count": 1000, "percentage": 11.8}
]
}
Examples:
mp inspect engagement --from 2024-01-01 --to 2024-01-31
mp inspect engagement --from 2024-01-01 --to 2024-01-31 -e Purchase
mp inspect engagement --from 2024-01-01 --to 2024-01-31 --buckets 1,5,10,50,100
jq Examples:
--jq '.total_users' # Get total users
--jq '.buckets | [.[] | select(.bucket_min >= 10)]' # Power users (high engagement)
--jq '.buckets | .[] | select(.bucket_min == 1) | .percentage' # Single-event user percentage
--jq '.buckets | [.[].bucket_label]' # Get bucket labels only
Usage:
Options:
--from TEXT Start date (YYYY-MM-DD). \[required]
--to TEXT End date (YYYY-MM-DD). \[required]
-e, --events TEXT Comma-separated event names (or all if omitted).
--buckets TEXT Comma-separated bucket boundaries (e.g., 1,5,10,50).
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
events¶
List all event names from Mixpanel project.
Calls the Mixpanel API to retrieve tracked event types. Use this to discover what events exist before fetching or querying.
Output Structure (JSON):
["Sign Up", "Login", "Purchase", "Page View", "Add to Cart"]
Examples:
mp inspect events
mp inspect events --format table
mp inspect events --format json --jq '.[0:3]'
jq Examples:
--jq '.[0:5]' # Get first 5 events
--jq 'length' # Count total events
--jq '[.[] | select(contains("Purchase"))]' # Find events containing "Purchase"
--jq 'sort' # Sort alphabetically
Usage:
Options:
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
funnels¶
List saved funnels in Mixpanel project.
Calls the Mixpanel API to retrieve saved funnel definitions. Use the funnel_id with 'mp query funnel' to run funnel analysis.
Output Structure (JSON):
[
{"funnel_id": 12345, "name": "Onboarding Flow"},
{"funnel_id": 12346, "name": "Purchase Funnel"},
{"funnel_id": 12347, "name": "Trial to Paid"}
]
Examples:
mp inspect funnels
mp inspect funnels --format table
jq Examples:
--jq '[.[].funnel_id]' # Get all funnel IDs
--jq '.[] | select(.name | test("Purchase"; "i"))' # Find funnel by name pattern
--jq '[.[].name]' # Get funnel names only
--jq 'length' # Count funnels
Usage:
Options:
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
info¶
Show workspace information.
Shows current account configuration, database location, and connection status. Uses local configuration only (no API call).
Output Structure (JSON):
{
"path": "/path/to/mixpanel.db",
"project_id": "12345",
"region": "us",
"account": "production",
"tables": ["events", "profiles"],
"size_mb": 42.5,
"created_at": "2024-01-10T08:00:00"
}
Examples:
mp inspect info
mp inspect info --format json
jq Examples:
--jq '.path' # Get database path
--jq '.project_id' # Get project ID
--jq '.tables' # Get list of tables
--jq '.size_mb' # Get database size in MB
Usage:
Options:
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
keys¶
List JSON property keys in a table.
Extracts distinct keys from the 'properties' JSON column. Useful for discovering queryable fields in event properties.
Output Structure (JSON):
["amount", "browser", "campaign", "country", "currency", "device", "platform"]
Examples:
mp inspect keys -t events
mp inspect keys -t events -e "Purchase"
mp inspect keys -t events --format table
jq Examples:
--jq '.[0:10]' # Get first 10 keys
--jq 'length' # Count total property keys
--jq '[.[] | select(contains("utm"))]' # Find keys containing "utm"
--jq 'sort' # Sort keys alphabetically
Usage:
Options:
-t, --table TEXT Table name. \[required]
-e, --event TEXT Filter to specific event type.
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
lexicon-schema¶
Get a single Lexicon schema from Mixpanel data dictionary.
Retrieves the full schema definition for a specific event or profile property, including all property definitions and metadata.
Output Structure (JSON):
{
"entity_type": "event",
"name": "Purchase",
"schema_json": {
"description": "User completed a purchase",
"properties": {
"amount": {"type": "number", "description": "Purchase amount in USD"},
"currency": {"type": "string", "description": "Currency code"},
"product_id": {"type": "string", "description": "Product identifier"}
},
"metadata": {"hidden": false, "dropped": false, "tags": ["revenue"]}
}
}
Examples:
mp inspect lexicon-schema --type event --name "Purchase"
mp inspect lexicon-schema -t event -n "Sign Up"
mp inspect lexicon-schema -t profile -n "Plan Type" --format json
jq Examples:
--jq '.schema_json.properties | keys' # Get property names only
--jq '.schema_json.properties | to_entries | [.[] | {name: .key, type: .value.type}]' # Get property types
--jq '.schema_json.description' # Get description
--jq '.schema_json.metadata.hidden' # Check if schema is hidden
Usage:
Options:
-t, --type TEXT Entity type: event, profile, custom_event, etc.
\[required]
-n, --name TEXT Entity name. \[required]
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
lexicon-schemas¶
List Lexicon schemas from Mixpanel data dictionary.
Retrieves documented event and profile property schemas from the Mixpanel Lexicon. Shows schema names, types, and property counts.
Output Structure (JSON):
[
{"entity_type": "event", "name": "Purchase", "property_count": 12, "description": "User completed purchase"},
{"entity_type": "event", "name": "Sign Up", "property_count": 8, "description": "New user registration"},
{"entity_type": "profile", "name": "Plan Type", "property_count": 3, "description": "User subscription tier"}
]
Examples:
mp inspect lexicon-schemas
mp inspect lexicon-schemas --type event
mp inspect lexicon-schemas --type profile --format table
jq Examples:
--jq '[.[] | select(.entity_type == "event")]' # Get only event schemas
--jq '[.[].name]' # Get schema names
--jq '[.[] | select(.property_count > 10)]' # Schemas with many properties
--jq '[.[] | select(.description | test("purchase"; "i"))]' # Search by description
Usage:
Options:
-t, --type TEXT Entity type: event, profile, custom_event, etc.
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
numeric¶
Show numeric property statistics from Mixpanel.
Uses JQL to compute min, max, avg, stddev, and percentiles for a numeric property. Useful for understanding value ranges and distributions.
Output Structure (JSON):
{
"event": "Purchase",
"property_name": "amount",
"from_date": "2024-01-01",
"to_date": "2024-01-31",
"count": 5000,
"min": 9.99,
"max": 999.99,
"sum": 125000.50,
"avg": 25.00,
"stddev": 45.75,
"percentiles": {"25": 12.99, "50": 19.99, "75": 49.99, "90": 99.99}
}
Examples:
mp inspect numeric -e Purchase -p amount --from 2024-01-01 --to 2024-01-31
mp inspect numeric -e Purchase -p amount --from 2024-01-01 --to 2024-01-31 --percentiles 10,50,90
jq Examples:
--jq '.avg' # Get average value
--jq '.percentiles["50"]' # Get median (50th percentile)
--jq '{min, max}' # Get min and max
--jq '.percentiles' # Get all percentiles
Usage:
Options:
-e, --event TEXT Event name to analyze. \[required]
-p, --property TEXT Numeric property name. \[required]
--from TEXT Start date (YYYY-MM-DD). \[required]
--to TEXT End date (YYYY-MM-DD). \[required]
--percentiles TEXT Comma-separated percentiles (e.g., 25,50,75,90).
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
properties¶
List properties for a specific event.
Calls the Mixpanel API to retrieve property names tracked with an event. Shows both custom event properties and default Mixpanel properties.
Output Structure (JSON):
["country", "browser", "device", "$city", "$region", "plan_type"]
Examples:
mp inspect properties -e "Sign Up"
mp inspect properties -e "Purchase" --format table
jq Examples:
--jq '.[0:10]' # Get first 10 properties
--jq '[.[] | select(startswith("$") | not)]' # User-defined properties (no $ prefix)
--jq '[.[] | select(startswith("$"))]' # Mixpanel system properties ($ prefix)
--jq 'length' # Count properties
Usage:
Options:
-e, --event TEXT Event name. \[required]
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
sample¶
Show random sample rows from a table.
Uses reservoir sampling to return representative rows from throughout the table. Useful for quickly exploring data structure and values.
Output Structure (JSON):
[
{
"event_name": "Purchase",
"event_time": "2024-01-15T10:30:00",
"distinct_id": "user_123",
"properties": {"amount": 99.99, "currency": "USD", "product": "Pro Plan"}
},
{
"event_name": "Login",
"event_time": "2024-01-15T09:15:00",
"distinct_id": "user_456",
"properties": {"browser": "Chrome", "platform": "web"}
}
]
Examples:
mp inspect sample -t events
mp inspect sample -t events -n 5 --format json
jq Examples:
--jq '[.[].event_name]' # Get event names from sample
--jq '[.[].distinct_id] | unique' # Get unique distinct_ids
--jq '[.[].properties.country]' # Extract specific property
--jq '[.[] | select(.event_name == "Purchase")]' # Filter sample by event type
Usage:
Options:
-t, --table TEXT Table name. \[required]
-n, --rows INTEGER Number of rows to sample. \[default: 10]
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
schema¶
Show schema for a table in local database.
Lists all columns with their types and nullability constraints. Useful for understanding the data structure before writing SQL.
Note: The --sample option is reserved for future implementation.
Output Structure (JSON):
{
"table": "events",
"columns": [
{"name": "event_name", "type": "VARCHAR", "nullable": false},
{"name": "event_time", "type": "TIMESTAMP", "nullable": false},
{"name": "distinct_id", "type": "VARCHAR", "nullable": false},
{"name": "properties", "type": "JSON", "nullable": true}
]
}
Examples:
mp inspect schema -t events
mp inspect schema -t events --format table
jq Examples:
--jq '.columns | [.[].name]' # Get column names only
--jq '.columns | [.[] | select(.nullable)]' # Get nullable columns
--jq '.columns | [.[] | {name, type}]' # Get column types
--jq '.columns | length' # Count columns
Usage:
Options:
-t, --table TEXT Table name. \[required]
--sample Include sample values.
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
summarize¶
Show statistical summary of all columns in a table.
Uses DuckDB's SUMMARIZE command to compute per-column statistics including min/max, quartiles, null percentage, and distinct counts.
Output Structure (JSON):
{
"table": "events",
"row_count": 125000,
"columns": [
{
"column_name": "event_name",
"column_type": "VARCHAR",
"min": "Add to Cart",
"max": "View Page",
"approx_unique": 25,
"avg": null,
"std": null,
"q25": null,
"q50": null,
"q75": null,
"count": 125000,
"null_percentage": 0.0
}
]
}
Examples:
mp inspect summarize -t events
mp inspect summarize -t events --format json
jq Examples:
--jq '.columns | [.[].column_name]' # Get column names
--jq '.columns | [.[] | select(.null_percentage > 0)]' # Find columns with nulls
--jq '.row_count' # Get row count
--jq '.columns | [.[] | select(.approx_unique > 1000)]' # High-cardinality columns
Usage:
Options:
-t, --table TEXT Table name. \[required]
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
tables¶
List tables in local database.
Shows all tables in the local DuckDB database with row counts and fetch timestamps. Use this to see what data has been fetched.
Output Structure (JSON):
[
{"name": "events", "type": "events", "row_count": 125000, "fetched_at": "2024-01-15T10:30:00"},
{"name": "jan_events", "type": "events", "row_count": 45000, "fetched_at": "2024-01-10T08:00:00"},
{"name": "profiles", "type": "profiles", "row_count": 8500, "fetched_at": "2024-01-14T14:20:00"}
]
Examples:
mp inspect tables
mp inspect tables --format table
jq Examples:
--jq '[.[].name]' # Get table names only
--jq '[.[] | select(.row_count > 100000)]' # Tables with more than 100k rows
--jq '[.[] | select(.type == "events")]' # Get only event tables
--jq '[.[].row_count] | add' # Total row count across all tables
Usage:
Options:
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
top-events¶
List today's top events by count.
Calls the Mixpanel API to retrieve today's most frequent events. Useful for quick overview of project activity.
Output Structure (JSON):
[
{"event": "Page View", "count": 15234, "percent_change": 12.5},
{"event": "Login", "count": 8921, "percent_change": -3.2},
{"event": "Purchase", "count": 1456, "percent_change": 8.7}
]
Examples:
mp inspect top-events
mp inspect top-events --limit 20 --format table
mp inspect top-events --type unique
jq Examples:
--jq '[.[] | select(.percent_change > 0)]' # Events with positive growth
--jq '[.[].event]' # Get just event names
--jq '[.[] | select(.count > 10000)]' # Events with count over 10000
--jq 'max_by(.percent_change)' # Event with highest growth
Usage:
Options:
-t, --type TEXT Count type: general, unique, average. \[default:
general]
-l, --limit INTEGER Maximum events to return. \[default: 10]
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
values¶
List sample values for a property.
Calls the Mixpanel API to retrieve sample values for a property. Useful for understanding the data shape before writing queries.
Output Structure (JSON):
["US", "UK", "DE", "FR", "CA", "AU", "JP"]
Examples:
mp inspect values -p country
mp inspect values -p country -e "Sign Up" --limit 20
mp inspect values -p browser --format table
jq Examples:
--jq '.[0:5]' # Get first 5 values
--jq 'length' # Count unique values
--jq '[.[] | select(test("^U"))]' # Filter values matching pattern
--jq 'sort' # Sort values alphabetically
Usage:
Options:
-p, --property TEXT Property name. \[required]
-e, --event TEXT Event name (optional).
-l, --limit INTEGER Maximum values to return. \[default: 100]
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
query¶
Query local and live data.
Usage:
activity-feed¶
Query user activity feed for specific users.
Retrieves the event history for one or more users identified by their distinct_id. Pass comma-separated IDs to --users.
Optionally filter by date range with --from and --to. Without date filters, returns recent activity (API default).
Output Structure (JSON):
{
"distinct_ids": ["user123", "user456"],
"from_date": "2025-01-01",
"to_date": "2025-01-31",
"event_count": 47,
"events": [
{
"event": "Login",
"time": "2025-01-15T10:30:00+00:00",
"properties": {"$browser": "Chrome", "$city": "San Francisco", ...}
},
{
"event": "Purchase",
"time": "2025-01-15T11:45:00+00:00",
"properties": {"product_id": "SKU123", "amount": 99.99, ...}
}
]
}
Examples:
mp query activity-feed --users "user123"
mp query activity-feed --users "user123,user456" --from 2025-01-01 --to 2025-01-31
mp query activity-feed --users "user123" --format table
jq Examples:
--jq '.event_count' # Total number of events
--jq '.events | length' # Same as above
--jq '.events[].event' # List all event names
--jq '.events | group_by(.event) | map({event: .[0].event, count: length})'
Usage:
Options:
-U, --users TEXT Comma-separated distinct IDs. \[required]
--from TEXT Start date (YYYY-MM-DD).
--to TEXT End date (YYYY-MM-DD).
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
event-counts¶
Query event counts over time for multiple events.
Compares multiple events on the same time series. Pass comma-separated event names to --events (e.g., --events "Sign Up,Login,Purchase").
The --type option controls how counts are calculated: - general: Total event occurrences (default) - unique: Unique users who triggered the event - average: Average events per user
Output Structure (JSON):
{
"events": ["Sign Up", "Login", "Purchase"],
"from_date": "2025-01-01",
"to_date": "2025-01-07",
"unit": "day",
"type": "general",
"series": {
"Sign Up": {"2025-01-01": 150, "2025-01-02": 175, ...},
"Login": {"2025-01-01": 520, "2025-01-02": 610, ...},
"Purchase": {"2025-01-01": 45, "2025-01-02": 52, ...}
}
}
Examples:
mp query event-counts --events "Sign Up,Login,Purchase" --from 2025-01-01 --to 2025-01-31
mp query event-counts --events "Sign Up,Purchase" --from 2025-01-01 --to 2025-01-31 --type unique
mp query event-counts --events "Login" --from 2025-01-01 --to 2025-01-31 --unit week
jq Examples:
--jq '.series | keys' # List event names
--jq '.series["Login"] | add' # Sum counts for one event
--jq '.series["Login"]["2025-01-01"]' # Count for specific date
--jq '[.series | to_entries[] | {event: .key, total: (.value | add)}]'
Usage:
Options:
-e, --events TEXT Comma-separated event names. \[required]
--from TEXT Start date (YYYY-MM-DD). \[required]
--to TEXT End date (YYYY-MM-DD). \[required]
-t, --type TEXT Count type: general, unique, average. \[default:
general]
-u, --unit TEXT Time unit: day, week, month. \[default: day]
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
flows¶
Query a saved Flows report by bookmark ID.
Retrieves data from a saved Flows report in Mixpanel. The bookmark_id can be found in the URL when viewing a flows report (the numeric ID after /flows/).
Flows reports show user paths through a sequence of events with step-by-step conversion rates and path breakdowns.
Output Structure (JSON):
{
"bookmark_id": 12345,
"computed_at": "2025-01-15T10:30:00Z",
"steps": [
{"step": 1, "event": "Sign Up", "count": 10000},
{"step": 2, "event": "Verify Email", "count": 7500},
{"step": 3, "event": "Complete Profile", "count": 4200}
],
"breakdowns": [
{"path": ["Sign Up", "Verify Email", "Complete Profile"], "count": 3800},
{"path": ["Sign Up", "Verify Email", "Drop Off"], "count": 3300}
],
"overall_conversion_rate": 0.42,
"metadata": {...}
}
Examples:
mp query flows 12345
mp query flows 12345 --format table
jq Examples:
--jq '.overall_conversion_rate' # End-to-end conversion rate
--jq '.steps | length' # Number of flow steps
--jq '.steps[] | {event, count}' # Event and count per step
--jq '.breakdowns | sort_by(.count) | reverse | .[0]'
Usage:
Options:
BOOKMARK_ID Saved flows report bookmark ID. \[required]
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
frequency¶
Analyze event frequency distribution (addiction analysis).
Shows how many users performed an event N times within each time period. Useful for understanding user engagement depth and "power user" distribution.
The --addiction-unit controls granularity of frequency buckets (hour or day). For example, with --addiction-unit hour, the data shows how many users performed the event 1 time, 2 times, 3 times, etc. per hour.
Output Structure (JSON):
{
"event": "Login",
"from_date": "2025-01-01",
"to_date": "2025-01-07",
"unit": "day",
"addiction_unit": "hour",
"data": {
"2025-01-01": [500, 250, 125, 60, 30, 15],
"2025-01-02": [520, 260, 130, 65, 32, 16],
...
}
}
Each array shows user counts by frequency (index 0 = 1x, index 1 = 2x, etc.).
Examples:
mp query frequency --from 2025-01-01 --to 2025-01-31
mp query frequency -e "Login" --from 2025-01-01 --to 2025-01-31
mp query frequency -e "Login" --from 2025-01-01 --to 2025-01-31 --addiction-unit day
jq Examples:
--jq '.data | keys' # List all dates
--jq '.data["2025-01-01"][0]' # Users who did it once on Jan 1
--jq '.data["2025-01-01"] | add' # Total active users on Jan 1
--jq '.data | to_entries | map({date: .key, power_users: .value[4:] | add})'
Usage:
Options:
--from TEXT Start date (YYYY-MM-DD). \[required]
--to TEXT End date (YYYY-MM-DD). \[required]
-e, --event TEXT Event name (all events if omitted).
-u, --unit TEXT Time unit: day, week, month. \[default: day]
--addiction-unit TEXT Addiction unit: hour, day. \[default: hour]
-w, --where TEXT Filter expression.
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format
json or jsonl).
funnel¶
Run live funnel analysis against Mixpanel API.
Analyzes conversion through a saved funnel's steps. The funnel_id can be found in the Mixpanel UI URL when viewing the funnel, or via 'mp inspect funnels'.
Output Structure (JSON):
{
"funnel_id": 12345,
"funnel_name": "Onboarding Funnel",
"from_date": "2025-01-01",
"to_date": "2025-01-31",
"conversion_rate": 0.23,
"steps": [
{"event": "Sign Up", "count": 10000, "conversion_rate": 1.0},
{"event": "Verify Email", "count": 7500, "conversion_rate": 0.75},
{"event": "Complete Profile", "count": 4200, "conversion_rate": 0.56},
{"event": "First Purchase", "count": 2300, "conversion_rate": 0.55}
]
}
Examples:
mp query funnel 12345 --from 2025-01-01 --to 2025-01-31
mp query funnel 12345 --from 2025-01-01 --to 2025-01-31 --unit week
mp query funnel 12345 --from 2025-01-01 --to 2025-01-31 --on country
jq Examples:
--jq '.conversion_rate' # Overall conversion rate
--jq '.steps | length' # Number of funnel steps
--jq '.steps[-1].count' # Users completing the funnel
--jq '.steps[] | {event, rate: .conversion_rate}'
Usage:
Options:
FUNNEL_ID Funnel ID. \[required]
--from TEXT Start date (YYYY-MM-DD). \[required]
--to TEXT End date (YYYY-MM-DD). \[required]
-u, --unit TEXT Time unit: day, week, month.
-o, --on TEXT Property to segment by.
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
jql¶
Execute JQL script against Mixpanel API.
Script can be provided as a file argument or inline with --script. Parameters can be passed with --param key=value (repeatable).
Output Structure (JSON):
The output structure depends on your JQL script. Common patterns:
groupBy result:
{
"raw": [
{"key": ["Login"], "value": 5234},
{"key": ["Sign Up"], "value": 1892}
],
"row_count": 2
}
Aggregation result:
{
"raw": [{"count": 15234, "unique_users": 3421}],
"row_count": 1
}
Examples:
mp query jql analysis.js
mp query jql --script "function main() { return Events({...}).groupBy(['event'], mixpanel.reducer.count()) }"
mp query jql analysis.js --param start_date=2025-01-01 --param event_name=Login
jq Examples:
--jq '.raw' # Get raw result array
--jq '.raw[0]' # First result row
--jq '.raw[] | {event: .key[0], count: .value}'
--jq '.row_count' # Number of result rows
Usage:
Options:
[FILE] JQL script file.
-c, --script TEXT Inline JQL script.
-P, --param TEXT Parameter (key=value).
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
property-counts¶
Query event counts broken down by property values.
Shows how event counts vary across different values of a property. For example, --property country shows event counts per country.
The --type option controls how counts are calculated: - general: Total event occurrences (default) - unique: Unique users who triggered the event - average: Average events per user
The --limit option controls how many property values to return (default 10, ordered by count descending).
Output Structure (JSON):
{
"event": "Purchase",
"property_name": "country",
"from_date": "2025-01-01",
"to_date": "2025-01-07",
"unit": "day",
"type": "general",
"series": {
"US": {"2025-01-01": 150, "2025-01-02": 175, ...},
"UK": {"2025-01-01": 75, "2025-01-02": 80, ...},
"DE": {"2025-01-01": 45, "2025-01-02": 52, ...}
}
}
Examples:
mp query property-counts -e "Purchase" -p country --from 2025-01-01 --to 2025-01-31
mp query property-counts -e "Sign Up" -p "utm_source" --from 2025-01-01 --to 2025-01-31 --limit 20
mp query property-counts -e "Login" -p browser --from 2025-01-01 --to 2025-01-31 --type unique
jq Examples:
--jq '.series | keys' # List property values
--jq '.series["US"] | add' # Sum counts for one value
--jq '.series | to_entries | sort_by(.value | add) | reverse'
--jq '[.series | to_entries[] | {value: .key, total: (.value | add)}]'
Usage:
Options:
-e, --event TEXT Event name. \[required]
-p, --property TEXT Property name. \[required]
--from TEXT Start date (YYYY-MM-DD). \[required]
--to TEXT End date (YYYY-MM-DD). \[required]
-t, --type TEXT Count type: general, unique, average. \[default:
general]
-u, --unit TEXT Time unit: day, week, month. \[default: day]
-l, --limit INTEGER Max property values to return. \[default: 10]
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
retention¶
Run live retention analysis against Mixpanel API.
Measures how many users return after their first action (birth event). Users are grouped into cohorts by when they first did the birth event, then tracked for how many returned to do the return event.
The --interval and --intervals options control bucket granularity: --interval is the bucket size (default 1), --intervals is the number of buckets to track (default 10). Combined with --unit, this defines the retention window (e.g., --unit day --interval 1 --intervals 7 tracks daily retention for 7 days).
Output Structure (JSON):
{
"born_event": "Sign Up",
"return_event": "Login",
"from_date": "2025-01-01",
"to_date": "2025-01-31",
"unit": "day",
"cohorts": [
{"date": "2025-01-01", "size": 500, "retention": [1.0, 0.65, 0.45, 0.38]},
{"date": "2025-01-02", "size": 480, "retention": [1.0, 0.62, 0.41, 0.35]},
{"date": "2025-01-03", "size": 520, "retention": [1.0, 0.68, 0.48, 0.40]}
]
}
Examples:
mp query retention --born "Sign Up" --return "Login" --from 2025-01-01 --to 2025-01-31
mp query retention --born "Sign Up" --return "Purchase" --from 2025-01-01 --to 2025-01-31 --unit week
mp query retention --born "Sign Up" --return "Login" --from 2025-01-01 --to 2025-01-31 --intervals 7
jq Examples:
--jq '.cohorts | length' # Number of cohorts
--jq '.cohorts[0].retention' # First cohort retention curve
--jq '.cohorts[] | {date, size, day7: .retention[7]}'
Usage:
Options:
-b, --born TEXT Birth event. \[required]
-r, --return TEXT Return event. \[required]
--from TEXT Start date (YYYY-MM-DD). \[required]
--to TEXT End date (YYYY-MM-DD). \[required]
--born-where TEXT Birth event filter.
--return-where TEXT Return event filter.
-i, --interval INTEGER Bucket size.
-n, --intervals INTEGER Number of buckets.
-u, --unit TEXT Time unit: day, week, month. \[default: day]
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format
json or jsonl).
saved-report¶
Query a saved report (Insights, Retention, or Funnel) by bookmark ID.
Retrieves data from a saved report in Mixpanel. The bookmark_id can be found in the URL when viewing a report (the numeric ID after /insights/, /retention/, or /funnels/).
The report type is automatically detected from the response headers.
Output Structure (JSON):
Insights report:
{
"bookmark_id": 12345,
"computed_at": "2025-01-15T10:30:00Z",
"from_date": "2025-01-01",
"to_date": "2025-01-31",
"headers": ["$event"],
"series": {
"Sign Up": {"2025-01-01": 150, "2025-01-02": 175, ...},
"Login": {"2025-01-01": 520, "2025-01-02": 610, ...}
},
"report_type": "insights"
}
Funnel/Retention reports have different series structures based on the saved report configuration.
Examples:
mp query saved-report 12345
mp query saved-report 12345 --format table
jq Examples:
--jq '.report_type' # Report type (insights/retention/funnel)
--jq '.series | keys' # List series names
--jq '.headers' # Report column headers
--jq '.series | to_entries | map({name: .key, total: (.value | add)})'
Usage:
Options:
BOOKMARK_ID Saved report bookmark ID. \[required]
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
segmentation¶
Run live segmentation query against Mixpanel API.
Returns time-series event counts, optionally segmented by a property. Without --on, returns total counts per time period. With --on, breaks down counts by property values (e.g., --on country shows counts per country).
The --on parameter accepts bare property names (e.g., 'country') or full filter expressions (e.g., 'properties["country"] == "US"').
Output Structure (JSON):
{
"event": "Sign Up",
"from_date": "2025-01-01",
"to_date": "2025-01-07",
"unit": "day",
"segment_property": "country",
"total": 1850,
"series": {
"US": {"2025-01-01": 150, "2025-01-02": 175, ...},
"UK": {"2025-01-01": 75, "2025-01-02": 80, ...}
}
}
Examples:
mp query segmentation -e "Sign Up" --from 2025-01-01 --to 2025-01-31
mp query segmentation -e "Purchase" --from 2025-01-01 --to 2025-01-31 --on country
mp query segmentation -e "Login" --from 2025-01-01 --to 2025-01-07 --unit week
jq Examples:
--jq '.total' # Total event count
--jq '.series | keys' # List segment names
--jq '.series["US"] | add' # Sum counts for one segment
Usage:
Options:
-e, --event TEXT Event name. \[required]
--from TEXT Start date (YYYY-MM-DD). \[required]
--to TEXT End date (YYYY-MM-DD). \[required]
-o, --on TEXT Property to segment by (bare name or expression).
-u, --unit TEXT Time unit: day, week, month. \[default: day]
-w, --where TEXT Filter expression.
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
segmentation-average¶
Calculate average of numeric property over time.
Calculates the mean value of a numeric property across all matching events. Useful for tracking averages like order value, session duration, or scores.
For example, --event Purchase --on order_value calculates average order value per time period.
Output Structure (JSON):
{
"event": "Purchase",
"from_date": "2025-01-01",
"to_date": "2025-01-07",
"property_expr": "order_value",
"unit": "day",
"results": {
"2025-01-01": 85.50,
"2025-01-02": 92.75,
"2025-01-03": 78.25,
...
}
}
Examples:
mp query segmentation-average -e "Purchase" --on order_value --from 2025-01-01 --to 2025-01-31
mp query segmentation-average -e "Session" --on duration --from 2025-01-01 --to 2025-01-31 --unit hour
jq Examples:
--jq '.results | add / length' # Overall average
--jq '.results | to_entries | max_by(.value)' # Highest day
--jq '.results | to_entries | min_by(.value)' # Lowest day
--jq '[.results | to_entries[] | {date: .key, avg: .value}]'
Usage:
Options:
-e, --event TEXT Event name. \[required]
-o, --on TEXT Numeric property to average (bare name or expression).
\[required]
--from TEXT Start date (YYYY-MM-DD). \[required]
--to TEXT End date (YYYY-MM-DD). \[required]
-u, --unit TEXT Time unit: hour, day. \[default: day]
-w, --where TEXT Filter expression.
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
segmentation-numeric¶
Bucket events by numeric property ranges.
Groups events into buckets based on a numeric property's value. Mixpanel automatically determines optimal bucket ranges based on the property's value distribution.
For example, --on price might create buckets like "0-10", "10-50", "50+".
The --type option controls how counts are calculated: - general: Total event occurrences (default) - unique: Unique users who triggered the event - average: Average events per user
Output Structure (JSON):
{
"event": "Purchase",
"from_date": "2025-01-01",
"to_date": "2025-01-07",
"property_expr": "amount",
"unit": "day",
"series": {
"0-50": {"2025-01-01": 120, "2025-01-02": 135, ...},
"50-100": {"2025-01-01": 85, "2025-01-02": 92, ...},
"100-500": {"2025-01-01": 45, "2025-01-02": 52, ...},
"500+": {"2025-01-01": 12, "2025-01-02": 15, ...}
}
}
Examples:
mp query segmentation-numeric -e "Purchase" --on amount --from 2025-01-01 --to 2025-01-31
mp query segmentation-numeric -e "Purchase" --on amount --from 2025-01-01 --to 2025-01-31 --type unique
jq Examples:
--jq '.series | keys' # List bucket ranges
--jq '.series["100-500"] | add' # Sum counts for a bucket
--jq '[.series | to_entries[] | {bucket: .key, total: (.value | add)}]'
--jq '.series | to_entries | sort_by(.value | add) | reverse'
Usage:
Options:
-e, --event TEXT Event name. \[required]
-o, --on TEXT Numeric property to bucket (bare name or expression).
\[required]
--from TEXT Start date (YYYY-MM-DD). \[required]
--to TEXT End date (YYYY-MM-DD). \[required]
-t, --type TEXT Count type: general, unique, average. \[default:
general]
-u, --unit TEXT Time unit: hour, day. \[default: day]
-w, --where TEXT Filter expression.
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
segmentation-sum¶
Calculate sum of numeric property over time.
Sums the values of a numeric property across all matching events. Useful for tracking totals like revenue, quantity, or duration.
For example, --event Purchase --on revenue calculates total revenue per time period.
Output Structure (JSON):
{
"event": "Purchase",
"from_date": "2025-01-01",
"to_date": "2025-01-07",
"property_expr": "revenue",
"unit": "day",
"results": {
"2025-01-01": 15234.50,
"2025-01-02": 18456.75,
"2025-01-03": 12890.25,
...
}
}
Examples:
mp query segmentation-sum -e "Purchase" --on revenue --from 2025-01-01 --to 2025-01-31
mp query segmentation-sum -e "Purchase" --on quantity --from 2025-01-01 --to 2025-01-31 --unit hour
jq Examples:
--jq '.results | add' # Total sum across all dates
--jq '.results | to_entries | max_by(.value)' # Highest day
--jq '.results | to_entries | min_by(.value)' # Lowest day
--jq '[.results | to_entries[] | {date: .key, revenue: .value}]'
Usage:
Options:
-e, --event TEXT Event name. \[required]
-o, --on TEXT Numeric property to sum (bare name or expression).
\[required]
--from TEXT Start date (YYYY-MM-DD). \[required]
--to TEXT End date (YYYY-MM-DD). \[required]
-u, --unit TEXT Time unit: hour, day. \[default: day]
-w, --where TEXT Filter expression.
-f, --format [TEXT] Output format: json, jsonl, table, csv, plain.
\[default: json]
--jq TEXT Apply jq filter to JSON output (requires --format json
or jsonl).
sql¶
Execute SQL query against local DuckDB database.
Query can be provided as an argument or read from a file with --file. Use --scalar when your query returns a single value (e.g., COUNT(*)).
Output Structure (JSON):
Default (row results):
[
{"event": "Sign Up", "count": 1500},
{"event": "Login", "count": 3200},
{"event": "Purchase", "count": 450}
]
With --scalar:
{"value": 15234}
Examples:
mp query sql "SELECT COUNT(*) FROM events" --scalar
mp query sql "SELECT event, COUNT(*) FROM events GROUP BY 1" --format table
mp query sql --file analysis.sql --format csv
jq Examples:
--jq '.[0]' # First row
--jq '.[] | .event' # All event names
--jq 'map(select(.count > 100))' # Filter rows
--jq '.value' # Scalar result value
Usage:
Options: