CLI Commands¶
Complete reference for the mp command-line interface.
Explore on DeepWiki
Ask questions about specific commands, explore options, or get examples for your use case.
mp¶
Mixpanel data CLI - discover, query, and manage analytics data.
Usage:
Options:
-a, --account TEXT Account name to use (overrides default). \[env
var: MP_ACCOUNT]
-p, --project TEXT Project ID to use (overrides active context).
\[env var: MP_PROJECT_ID]
-w, --workspace INTEGER Workspace ID for this command. \[env var:
MP_WORKSPACE_ID]
-t, --target TEXT Apply a saved target (mutually exclusive with
--account/--project/--workspace). \[env var:
MP_TARGET]
-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.
account¶
Manage accounts.
Usage:
add¶
Add a new account.
For service_account, --username is required, --project is
required, and the secret is read from stdin (when --secret-stdin
is set) or from MP_SECRET. For oauth_token, --project is
required; supply --token-env (recommended) or set
MP_OAUTH_TOKEN and we'll capture it inline. For oauth_browser,
--project is optional and gets backfilled by mp account login.
Args:
ctx: Typer context.
name: Account name (alphanumeric, _, -).
type: service_account | oauth_browser | oauth_token.
region: us | eu | in.
project: Numeric project ID (becomes the account's default_project).
username: Required for service_account.
secret_stdin: Read secret from stdin instead of env.
token_env: Env var holding the bearer for oauth_token.
Usage:
Options:
NAME Account name (alphanumeric, _, -) \[required]
--type TEXT One of: service_account | oauth_browser | oauth_token
\[required]
--region TEXT Mixpanel region: us | eu | in \[required]
--project TEXT Numeric project ID (default_project). REQUIRED for
service_account and oauth_token; optional for
oauth_browser (backfilled by `mp account login`). Falls
back to MP_PROJECT_ID when omitted.
--username TEXT Username (service_account)
--secret-stdin Read secret from stdin (service_account; agent-friendly).
--token-env TEXT Env-var name holding the bearer (oauth_token).
export-bridge¶
Export the named (or active) account as a v2 bridge file at --to.
For oauth_browser accounts, embeds the on-disk OAuth tokens so the
consumer side (typically a Cowork VM) authenticates without re-running
PKCE. Settings-side [settings].custom_header propagates into the
bridge's headers block.
Usage:
Options:
--account TEXT Account to export (defaults to active)
--to PATH Destination bridge file path. \[default:
mixpanel_auth.json]
--project TEXT Pin a project ID into the bridge.
--workspace INTEGER Pin a workspace ID into the bridge.
list¶
List all configured accounts.
Shows the active account marker and any targets that reference each account (per FR-045, the first account auto-promotes to active).
Args: ctx: Typer context. format: Output format.
Usage:
Options:
login¶
Run the OAuth browser flow for an oauth_browser account.
Drives the PKCE login dance, persists tokens to
~/.mp/accounts/{name}/tokens.json, and probes /me to backfill
the account's default_project on first login. Prints a JSON
:class:OAuthLoginResult so scripts and the plugin can consume the
structured outcome.
Args:
ctx: Typer context.
name: Account name (must be oauth_browser type).
no_browser: Skip browser launch (manual URL copy).
Usage:
Options:
NAME OAuth browser account name. \[required]
--no-browser Skip launching the system browser (headless / SSH).
logout¶
Remove the on-disk OAuth tokens for an oauth_browser account.
Args: ctx: Typer context. name: Account name.
Usage:
Options:
remove¶
Remove an account.
Without --force, raises if any target references the account.
Args:
ctx: Typer context.
name: Account to remove.
force: When True, remove and orphan any referencing targets.
Usage:
Options:
NAME Account name to remove. \[required]
--force Remove even if referenced by targets (orphans them).
remove-bridge¶
Delete the bridge file at --at (or the resolved default path).
Idempotent — no error if the bridge is already absent (exit 0 either way).
Usage:
Options:
show¶
Show one account's summary (active by default).
Args:
ctx: Typer context.
name: Account name; None shows the active account.
format: Output format.
Usage:
Options:
test¶
Probe /me for the named (or active) account.
Never raises — failure is captured in the result's error field.
Args: ctx: Typer context. name: Account to test.
Usage:
Options:
token¶
Print the current bearer token for an OAuth account.
Returns N/A for service accounts (no bearer).
Args:
ctx: Typer context.
name: Account name; None uses the active account.
Usage:
Options:
update¶
Update fields on an existing account in place.
Only supplied flags are changed. Type cannot be changed via this command (remove + re-add for that). Type-incompatible flags raise an error.
Args: ctx: Typer context. name: Account name to update. region: New region. project: New default_project. username: New username (service_account only). secret_stdin: Read a new secret from stdin (service_account only). token_env: New env-var name (oauth_token only).
Usage:
Options:
NAME Account name to update. \[required]
--region TEXT New region: us | eu | in
--project TEXT New default_project (numeric project ID).
--username TEXT New username (service_account only).
--secret-stdin Read new secret from stdin (service_account only).
--token-env TEXT New env-var name (oauth_token only).
use¶
Set the active account, clearing any prior workspace pin.
Project travels with the account via Account.default_project, but
workspace IDs are project-scoped — a workspace ID set under the prior
account would resolve to a foreign workspace (or 404) under the new
one, so it's dropped on every account swap.
Args: ctx: Typer context. name: Account to activate.
Usage:
Options:
alerts¶
Manage Mixpanel custom alerts.
Usage:
bulk-delete¶
Bulk-delete custom alerts by IDs.
Permanently deletes multiple alerts. Provide IDs as a comma-separated string.
Args: ctx: Typer context with global options. ids: Comma-separated alert IDs.
Usage:
Options:
count¶
Get alert count and limits.
Retrieves the current alert count, account limit, and whether the account is below its limit.
Args: ctx: Typer context with global options. alert_type: Filter by alert type. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--type TEXT Filter by alert type.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
create¶
Create a new custom alert.
Creates a custom alert linked to a saved report (bookmark). The condition, subscriptions, and notification-windows options accept JSON strings.
Args: ctx: Typer context with global options. bookmark_id: Linked bookmark ID. name: Alert name. condition: Trigger condition as JSON string. frequency: Check frequency in seconds. paused: Whether to start paused. subscriptions: Notification targets as JSON string. notification_windows: Notification windows as JSON string. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--bookmark-id INTEGER Linked bookmark ID (required). \[required]
--name TEXT Alert name (required). \[required]
--condition TEXT Trigger condition as JSON string (required).
\[required]
--frequency INTEGER Check frequency in seconds (required).
\[required]
--paused / --no-paused Start paused or active. \[default: no-
paused]
--subscriptions TEXT Notification targets as JSON string.
--notification-windows TEXT Notification windows as JSON string.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
delete¶
Delete a custom alert.
Permanently deletes a custom alert by ID. This action cannot be undone.
Args: ctx: Typer context with global options. alert_id: Alert ID (integer).
Usage:
Options:
get¶
Get a single custom alert by ID.
Retrieves the full alert object including condition, subscriptions, and metadata.
Args: ctx: Typer context with global options. alert_id: Alert ID (integer). format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
ALERT_ID Alert ID. \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
history¶
View trigger history for a custom alert.
Retrieves the paginated trigger history for the specified alert.
Args: ctx: Typer context with global options. alert_id: Alert ID (integer). page_size: Number of results per page. cursor: Pagination cursor for next page. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
ALERT_ID Alert ID. \[required]
--page-size INTEGER Results per page.
--cursor TEXT Pagination cursor for next page.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
list¶
List custom alerts for the current project.
Retrieves all custom alerts visible to the authenticated user. Optionally filter by linked bookmark or list alerts for all users.
Args: ctx: Typer context with global options. bookmark_id: Filter by linked bookmark ID. skip_user_filter: Whether to list alerts for all users. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--bookmark-id INTEGER Filter by linked bookmark ID.
--skip-user-filter List alerts for all users.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
screenshot¶
Get a signed URL for an alert screenshot.
Retrieves a signed GCS URL that can be used to view the alert screenshot image.
Args: ctx: Typer context with global options. gcs_key: GCS object key for the screenshot. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--gcs-key TEXT GCS object key for the screenshot.
\[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
test¶
Send a test alert notification.
Sends a test notification using the provided alert parameters without actually creating the alert.
Args: ctx: Typer context with global options. bookmark_id: Linked bookmark ID. name: Alert name. condition: Trigger condition as JSON string. frequency: Check frequency in seconds. subscriptions: Notification targets as JSON string. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--bookmark-id INTEGER Linked bookmark ID. \[required]
--name TEXT Alert name. \[required]
--condition TEXT Trigger condition as JSON string.
\[required]
--frequency INTEGER Check frequency in seconds. \[required]
--subscriptions TEXT Notification targets as JSON string.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
update¶
Update an existing custom alert (PATCH semantics).
Only fields provided will be updated. Accepts JSON strings for condition, subscriptions, and notification-windows.
Args: ctx: Typer context with global options. alert_id: Alert ID (integer). name: New alert name. bookmark_id: New linked bookmark ID. condition: New condition as JSON string. frequency: New check frequency in seconds. paused: Pause or unpause alert. subscriptions: New notification targets as JSON string. notification_windows: New notification windows as JSON string. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
ALERT_ID Alert ID. \[required]
--name TEXT New alert name.
--bookmark-id INTEGER New linked bookmark ID.
--condition TEXT New condition as JSON string.
--frequency INTEGER New check frequency in seconds.
--paused / --no-paused Pause or unpause alert.
--subscriptions TEXT New notification targets as JSON string.
--notification-windows TEXT New notification windows as JSON string.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
validate¶
Validate alerts against a bookmark configuration.
Checks whether the specified alerts are compatible with the given bookmark type and parameters.
Args: ctx: Typer context with global options. alert_ids: Comma-separated alert IDs. bookmark_type: Bookmark type to validate against. bookmark_params: Bookmark params as JSON string. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--alert-ids TEXT Comma-separated alert IDs to validate.
\[required]
--bookmark-type TEXT Bookmark type to validate against.
\[required]
--bookmark-params TEXT Bookmark params as JSON string. \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
annotations¶
Manage timeline annotations.
Usage:
create¶
Create a new timeline annotation.
Creates an annotation at the specified date with the given description. Optionally associate tag IDs and a creator user ID.
Args: ctx: Typer context with global options. date: Annotation date (ISO format, required). description: Annotation text (required). tags: Comma-separated tag IDs. user_id: Creator user ID. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--date TEXT Annotation date (ISO format, required).
\[required]
--description TEXT Annotation text (required). \[required]
--tags TEXT Comma-separated tag IDs to associate.
--user-id INTEGER Creator user ID.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
delete¶
Delete an annotation.
Permanently deletes an annotation by ID. This action cannot be undone.
Args: ctx: Typer context with global options. annotation_id: Annotation identifier.
Usage:
Options:
get¶
Get a single annotation by ID.
Retrieves the full annotation object including tags and user info.
Args: ctx: Typer context with global options. annotation_id: Annotation identifier. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
ANNOTATION_ID Annotation ID. \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
list¶
List timeline annotations.
Retrieves annotations for the project, optionally filtered by date range or tag IDs.
Args: ctx: Typer context with global options. from_date: Start date filter (ISO format). to_date: End date filter (ISO format). tags: Comma-separated tag IDs. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--from TEXT Start date filter (ISO format).
--to TEXT End date filter (ISO format).
--tags TEXT Comma-separated tag IDs to filter by.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
tags¶
Manage annotation tags.
Usage:
create¶
Create a new annotation tag.
Creates a tag that can be associated with annotations.
Args: ctx: Typer context with global options. name: Tag name (required). format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--name TEXT Tag name (required). \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
list¶
List annotation tags.
Retrieves all annotation tags for the project.
Args: ctx: Typer context with global options. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
update¶
Update an existing annotation.
Updates the specified annotation using PATCH semantics. Only provided fields are changed.
Args: ctx: Typer context with global options. annotation_id: Annotation identifier. description: New description. tags: Comma-separated tag IDs (replaces existing). format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
ANNOTATION_ID Annotation ID. \[required]
--description TEXT New description.
--tags TEXT Comma-separated tag IDs (replaces existing).
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
cohorts¶
Manage Mixpanel cohorts.
Usage:
bulk-delete¶
Delete multiple cohorts at once.
Permanently removes all cohorts whose IDs are provided.
Args: ctx: Typer context with global options. ids: Comma-separated cohort IDs to delete.
Usage:
Options:
bulk-update¶
Update multiple cohorts at once.
Accepts a JSON array of update entries. Each entry must include an
id field and may include name, description, and
definition fields.
Args: ctx: Typer context with global options. entries: JSON string with a list of update entries.
Example usage::
mp cohorts bulk-update --entries '[{"id": 1, "name": "Renamed"}]'
Usage:
Options:
--entries TEXT JSON string containing a list of cohort update entries. Each
entry must have an "id" field and optional "name",
"description", and "definition" fields. \[required]
create¶
Create a new cohort.
Creates a cohort with the given name and optional description, data group, and behavioral definition.
Args: ctx: Typer context with global options. name: Cohort name. description: Optional cohort description. data_group_id: Optional data group identifier. definition: Optional cohort definition as a JSON string. format: Output format (json, jsonl, table, csv, plain). jq_filter: Optional jq filter for JSON output.
Usage:
Options:
--name TEXT Cohort name (required). \[required]
--description TEXT Cohort description.
--data-group-id TEXT Data group identifier.
--definition TEXT Cohort definition as a JSON string.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
delete¶
Delete a single cohort.
Permanently removes the cohort with the given ID.
Args: ctx: Typer context with global options. cohort_id: The cohort identifier.
Usage:
Options:
get¶
Get a single cohort by ID.
Retrieves full cohort details including metadata, definition, and creator information.
Args: ctx: Typer context with global options. cohort_id: The cohort identifier. format: Output format (json, jsonl, table, csv, plain). jq_filter: Optional jq filter for JSON output.
Usage:
Options:
COHORT_ID Cohort ID to retrieve. \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
list¶
List cohorts from the Mixpanel App API.
Returns full cohort objects with all metadata. Optionally filter by data group ID or a specific set of cohort IDs.
Args: ctx: Typer context with global options. data_group_id: Optional data group filter. ids: Comma-separated cohort IDs to retrieve. format: Output format (json, jsonl, table, csv, plain). jq_filter: Optional jq filter for JSON output.
Usage:
Options:
--data-group-id TEXT Filter cohorts by data group ID.
--ids TEXT Comma-separated list of cohort IDs to filter
by.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
update¶
Update an existing cohort.
Updates the specified cohort with any provided fields. Only fields that are explicitly set will be sent to the API.
Args: ctx: Typer context with global options. cohort_id: The cohort identifier. name: Optional new cohort name. description: Optional new cohort description. definition: Optional new cohort definition as a JSON string. format: Output format (json, jsonl, table, csv, plain). jq_filter: Optional jq filter for JSON output.
Usage:
Options:
COHORT_ID Cohort ID to update. \[required]
--name TEXT New cohort name.
--description TEXT New cohort description.
--definition TEXT New cohort definition as a JSON string.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
custom-events¶
Manage custom events.
Usage:
create¶
Create a new custom event.
A custom event aliases one or more underlying events under a single display name. For example::
mp custom-events create --name "Page View" \
--alternative "Home Viewed" --alternative "Product Viewed"
Args: ctx: Typer context with global options. name: Display name for the new custom event. alternative: Underlying event names to alias. Repeatable. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--name TEXT Display name for the new custom event.
\[required]
--alternative TEXT Underlying event name to alias. Pass
--alternative multiple times to alias more
than one event. \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
delete¶
Delete a custom event.
Identify the custom event by either --id (preferred) or --name.
Name lookup uses :meth:Workspace.list_custom_events and errors if the
name is ambiguous or unknown. The DELETE always targets the resolved
custom_event_id so the data-definitions endpoint cannot silently
delete the wrong entry or a stray orphan lexicon row.
Permanently deletes a custom event. This action cannot be undone.
Args: ctx: Typer context with global options. custom_event_id: Custom event ID. Mutually exclusive with name. name: Custom event name. Resolved to an ID via list_custom_events.
Usage:
Options:
--id, --custom-event-id INTEGER
Custom event ID. Use this OR --name. Prefer
--id when known.
--name TEXT Custom event name. Resolved to an ID via
list_custom_events; errors if zero or
multiple custom events share the name.
list¶
List all custom events for the current project.
Retrieves all custom event definitions in the project.
Args: ctx: Typer context with global options. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
update¶
Update a custom event's lexicon entry.
Identify the custom event by either --id (preferred) or --name.
Name lookup uses :meth:Workspace.list_custom_events and errors if the
name is ambiguous or unknown.
Args: ctx: Typer context with global options. custom_event_id: Custom event ID. Mutually exclusive with name. name: Custom event name. Resolved to an ID via list_custom_events. hidden: Hide or show the event. dropped: Drop or undrop the event. description: New event description. verified: Mark as verified or not. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--id, --custom-event-id INTEGER
Custom event ID. Use this OR --name. Prefer
--id when known.
--name TEXT Custom event name. Resolved to an ID via
list_custom_events; errors if zero or
multiple custom events share the name.
--hidden / --no-hidden Hide or show the event.
--dropped / --no-dropped Drop or undrop the event.
--description TEXT New event description.
--verified / --no-verified Mark as verified or not.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
custom-properties¶
Manage custom properties.
Usage:
create¶
Create a new custom property.
Creates a custom property with either a display formula or behavior specification. The --display-formula and --behavior options are mutually exclusive. When using --display-formula, --composed-properties is required.
Args: ctx: Typer context with global options. name: Property name. resource_type: Resource type (events, people, group_profiles). display_formula: Formula expression. composed_properties: Referenced properties as JSON string. behavior: Behavior specification as JSON string. description: Property description. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--name TEXT Property name (required). \[required]
--resource-type TEXT Resource type: events, people,
group_profiles (required). \[required]
--display-formula TEXT Formula expression (mutually exclusive with
--behavior).
--composed-properties TEXT Referenced properties as JSON string.
--behavior TEXT Behavior specification as JSON string
(mutually exclusive with --display-formula).
--description TEXT Property description.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
delete¶
Delete a custom property.
Permanently deletes a custom property by ID. This action cannot be undone.
Args: ctx: Typer context with global options. id: Custom property ID (string).
Usage:
Options:
get¶
Get a single custom property by ID.
Retrieves the full custom property object including its formula, composed properties, and metadata.
Args: ctx: Typer context with global options. id: Custom property ID (string). format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--id TEXT Custom property ID (required). \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
list¶
List all custom properties for the current project.
Retrieves all custom properties defined in the project.
Args: ctx: Typer context with global options. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
update¶
Update an existing custom property (PUT semantics).
Updates a custom property by ID. Note that resource_type and data_group_id are immutable and cannot be changed.
Args: ctx: Typer context with global options. id: Custom property ID. name: New property name. description: New property description. display_formula: New formula expression. composed_properties: New referenced properties as JSON string. is_locked: Lock or unlock the property. is_visible: Show or hide the property. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--id TEXT Custom property ID (required). \[required]
--name TEXT New property name.
--description TEXT New property description.
--display-formula TEXT New formula expression.
--composed-properties TEXT New referenced properties as JSON string.
--is-locked / --no-is-locked Lock or unlock the property.
--is-visible / --no-is-visible Show or hide the property.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
validate¶
Validate a custom property formula without creating it.
Checks whether the provided custom property definition is valid. Does not create the property.
Args: ctx: Typer context with global options. name: Property name. resource_type: Resource type (events, people, group_profiles). display_formula: Formula expression to validate. composed_properties: Referenced properties as JSON string. behavior: Behavior specification as JSON string. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--name TEXT Property name (required). \[required]
--resource-type TEXT Resource type: events, people,
group_profiles (required). \[required]
--display-formula TEXT Formula expression to validate.
--composed-properties TEXT Referenced properties as JSON string.
--behavior TEXT Behavior specification as JSON string.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
dashboards¶
Manage Mixpanel dashboards.
Usage:
add-report¶
Add a report to a dashboard.
Clones the specified bookmark/report onto the dashboard and returns the updated dashboard.
Args: ctx: Typer context with global options. dashboard_id: Dashboard identifier. bookmark_id: Bookmark/report identifier to add. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
DASHBOARD_ID Dashboard ID. \[required]
BOOKMARK_ID Bookmark/report ID to add. \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
blueprint-create¶
Create a dashboard from a blueprint template.
Creates a new dashboard using the specified blueprint template type.
Args: ctx: Typer context with global options. template_type: Blueprint template type identifier. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
TEMPLATE_TYPE Blueprint template type identifier.
\[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
blueprints¶
List available dashboard blueprint templates.
Retrieves the catalog of blueprint templates that can be used to create pre-configured dashboards.
Args: ctx: Typer context with global options. include_reports: Whether to include report details. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--include-reports Include report details in templates.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
bulk-delete¶
Delete multiple dashboards.
Permanently deletes all specified dashboards. This action cannot be undone.
Args: ctx: Typer context with global options. ids: Comma-separated dashboard IDs to delete (required).
Usage:
Options:
create¶
Create a new dashboard.
Creates a dashboard with the specified title and optional settings. Use --duplicate to clone an existing dashboard.
Args: ctx: Typer context with global options. title: Dashboard title (required). description: Optional dashboard description. private: Whether to make the dashboard private. restricted: Whether to restrict dashboard access. duplicate: ID of an existing dashboard to duplicate. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--title TEXT Dashboard title. \[required]
--description TEXT Dashboard description.
--private / --no-private Set privacy (default: not set).
--restricted / --no-restricted Set restriction (default: not set).
--duplicate INTEGER ID of dashboard to duplicate.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
delete¶
Delete a dashboard.
Permanently deletes a dashboard by ID. This action cannot be undone.
Args: ctx: Typer context with global options. dashboard_id: Dashboard identifier.
Usage:
Options:
erf¶
Get ERF data for a dashboard.
Retrieves the ERF metrics data associated with the specified dashboard.
Args: ctx: Typer context with global options. dashboard_id: Dashboard identifier. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
DASHBOARD_ID Dashboard ID. \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
favorite¶
Favorite a dashboard.
Marks the specified dashboard as a favorite for the current user.
Args: ctx: Typer context with global options. dashboard_id: Dashboard identifier.
Usage:
Options:
get¶
Get a single dashboard by ID.
Retrieves the full dashboard object including metadata, permissions, and layout.
Args: ctx: Typer context with global options. dashboard_id: Dashboard identifier. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
DASHBOARD_ID Dashboard ID. \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
list¶
List dashboards for the current project.
Retrieves all dashboards visible to the authenticated user, optionally filtered by specific IDs.
Args: ctx: Typer context with global options. ids: Optional comma-separated dashboard IDs to filter by. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--ids TEXT Comma-separated dashboard IDs to filter by.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
pin¶
Pin a dashboard.
Pins the specified dashboard for the current project.
Args: ctx: Typer context with global options. dashboard_id: Dashboard identifier.
Usage:
Options:
rca¶
Create an RCA (Root Cause Analysis) dashboard.
Creates a dashboard for root cause analysis using the specified source ID and source data configuration.
Args: ctx: Typer context with global options. source_id: Source ID for RCA analysis (required). source_data: RCA source data as a JSON string (required). format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--source-id INTEGER Source ID for RCA analysis. \[required]
--source-data TEXT RCA source data as JSON string (e.g.
'{"type": "anomaly"}'). \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
remove-report¶
Remove a report from a dashboard.
Removes the specified bookmark/report from the dashboard and returns the updated dashboard.
Args: ctx: Typer context with global options. dashboard_id: Dashboard identifier. bookmark_id: Bookmark/report identifier to remove. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
DASHBOARD_ID Dashboard ID. \[required]
BOOKMARK_ID Bookmark/report ID to remove. \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
unfavorite¶
Unfavorite a dashboard.
Removes the specified dashboard from the current user's favorites.
Args: ctx: Typer context with global options. dashboard_id: Dashboard identifier.
Usage:
Options:
unpin¶
Unpin a dashboard.
Unpins the specified dashboard from the current project.
Args: ctx: Typer context with global options. dashboard_id: Dashboard identifier.
Usage:
Options:
update¶
Update an existing dashboard.
Updates the specified fields on a dashboard. Only provided options are sent to the API; omitted fields are unchanged.
Args: ctx: Typer context with global options. dashboard_id: Dashboard identifier. title: New title for the dashboard. description: New description for the dashboard. private: Set privacy (use --no-private to unset). restricted: Set restriction (use --no-restricted to unset). format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
DASHBOARD_ID Dashboard ID. \[required]
--title TEXT New dashboard title.
--description TEXT New dashboard description.
--private / --no-private Set privacy.
--restricted / --no-restricted Set restriction.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
update-report-link¶
Update a report link on a dashboard.
Changes the type of a report link on the specified dashboard.
Args: ctx: Typer context with global options. dashboard_id: Dashboard identifier. report_link_id: Report link identifier. link_type: Link type value (required).
Usage:
Options:
DASHBOARD_ID Dashboard ID. \[required]
REPORT_LINK_ID Report link ID. \[required]
--type TEXT Link type (e.g. 'embedded'). \[required]
update-text-card¶
Update a text card on a dashboard.
Updates the markdown content of a text card on the specified dashboard.
Args: ctx: Typer context with global options. dashboard_id: Dashboard identifier. text_card_id: Text card identifier. markdown: Markdown content for the text card.
Usage:
Options:
DASHBOARD_ID Dashboard ID. \[required]
TEXT_CARD_ID Text card ID. \[required]
--markdown TEXT Markdown content for the text card.
drop-filters¶
Manage drop filters.
Usage:
create¶
Create a new drop filter.
Creates a drop filter for the specified event with the given filter conditions. Returns the full list of drop filters after creation.
Args: ctx: Typer context with global options. event_name: Event name to filter. filters: Filter condition as JSON string. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--event-name TEXT Event name to filter (required).
\[required]
--filters TEXT Filter condition as JSON string (required).
\[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
delete¶
Delete a drop filter.
Permanently deletes a drop filter by ID. Returns the remaining list of drop filters.
Args: ctx: Typer context with global options. id: Drop filter ID. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--id INTEGER Drop filter ID (required). \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
limits¶
Get drop filter usage limits.
Retrieves the current count and maximum allowed drop filters for the project.
Args: ctx: Typer context with global options. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
list¶
List all drop filters for the current project.
Retrieves all drop filters configured for the project.
Args: ctx: Typer context with global options. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
update¶
Update an existing drop filter.
Updates a drop filter by ID. Only provided fields are changed. Returns the full list of drop filters after update.
Args: ctx: Typer context with global options. id: Drop filter ID. event_name: New event name. filters: New filter condition as JSON string. active: Enable or disable the filter. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--id INTEGER Drop filter ID (required). \[required]
--event-name TEXT New event name.
--filters TEXT New filter condition as JSON string.
--active / --no-active Enable or disable the filter.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
experiments¶
Manage Mixpanel experiments.
Usage:
archive¶
Archive an experiment.
Marks the specified experiment as archived. Archived experiments are hidden from default listings.
Args: ctx: Typer context with global options. experiment_id: Experiment identifier.
Usage:
Options:
conclude¶
Conclude an active experiment.
Transitions an experiment from active to concluded status, optionally specifying an end date.
Args: ctx: Typer context with global options. experiment_id: Experiment identifier. end_date: Optional end date in YYYY-MM-DD format. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
EXPERIMENT_ID Experiment ID. \[required]
--end-date TEXT End date for the experiment (YYYY-MM-DD).
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
create¶
Create a new experiment.
Creates an experiment with the specified name and optional settings.
Args: ctx: Typer context with global options. name: Experiment name (required). description: Optional experiment description. hypothesis: Optional experiment hypothesis. settings: Optional experiment settings as a JSON string. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--name TEXT Experiment name. \[required]
--description TEXT Experiment description.
--hypothesis TEXT Experiment hypothesis.
--settings TEXT Experiment settings as JSON string (e.g.
'{"confidence_level": 0.95}').
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
decide¶
Decide the outcome of a concluded experiment.
Records the decision for a concluded experiment, including whether it was successful and which variant won.
Args: ctx: Typer context with global options. experiment_id: Experiment identifier. success: Whether the experiment was successful. variant: Optional winning variant name. message: Optional decision message or rationale. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
EXPERIMENT_ID Experiment ID. \[required]
--success / --no-success Whether the experiment was successful.
\[required]
--variant TEXT Winning variant name.
--message TEXT Decision message or rationale.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
delete¶
Delete an experiment.
Permanently deletes an experiment by ID. This action cannot be undone.
Args: ctx: Typer context with global options. experiment_id: Experiment identifier.
Usage:
Options:
duplicate¶
Duplicate an experiment.
Creates a copy of the specified experiment with a new name. A name is required because the Mixpanel API does not support duplication without one.
Args: ctx: Typer context with global options. experiment_id: Experiment identifier. name: Name for the duplicated experiment (required). format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
EXPERIMENT_ID Experiment ID. \[required]
--name TEXT Name for the duplicated experiment
(required). \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
erf¶
List ERF experiments.
Retrieves ERF experiment data for the current project.
Args: ctx: Typer context with global options. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
get¶
Get a single experiment by ID.
Retrieves the full experiment object including metadata, variants, metrics, and status.
Args: ctx: Typer context with global options. experiment_id: Experiment identifier. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
EXPERIMENT_ID Experiment ID. \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
launch¶
Launch a draft experiment.
Transitions an experiment from draft to active status.
Args: ctx: Typer context with global options. experiment_id: Experiment identifier. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
EXPERIMENT_ID Experiment ID. \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
list¶
List experiments for the current project.
Retrieves all experiments visible to the authenticated user, optionally including archived experiments.
Args: ctx: Typer context with global options. include_archived: Whether to include archived experiments. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--include-archived Include archived experiments in results.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
restore¶
Restore an archived experiment.
Restores a previously archived experiment back to its prior state.
Args: ctx: Typer context with global options. experiment_id: Experiment identifier. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
EXPERIMENT_ID Experiment ID. \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
update¶
Update an existing experiment.
Updates the specified fields on an experiment. Only provided options are sent to the API; omitted fields are unchanged.
Args: ctx: Typer context with global options. experiment_id: Experiment identifier. name: New name for the experiment. description: New description for the experiment. hypothesis: New hypothesis for the experiment. variants: Variants as a JSON string. metrics: Metrics as a JSON string. settings: Settings as a JSON string. tags: Comma-separated tags. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
EXPERIMENT_ID Experiment ID. \[required]
--name TEXT New experiment name.
--description TEXT New experiment description.
--hypothesis TEXT New experiment hypothesis.
--variants TEXT Variants as JSON object string (e.g.
'{"control": {"weight": 50}}').
--metrics TEXT Metrics as JSON object string (e.g.
'{"primary": "Purchase"}').
--settings TEXT Settings as JSON string (e.g.
'{"confidence_level": 0.95}').
--tags TEXT Comma-separated tags.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
flags¶
Manage Mixpanel feature flags.
Usage:
archive¶
Archive a feature flag.
Soft-deletes a feature flag by moving it to the archived state. Archived flags are excluded from default listings.
Args: ctx: Typer context with global options. flag_id: Feature flag identifier.
Usage:
Options:
create¶
Create a new feature flag.
Creates a feature flag with the specified name and key. Optional parameters allow setting description, status, tags, serving method, and initial ruleset.
Args: ctx: Typer context with global options. name: Flag name (required). key: Unique machine-readable key (required). description: Optional flag description. status: Initial status (enabled, disabled, archived). tags: Comma-separated tags. serving_method: Serving method (client, server, remote_or_local, remote_only). ruleset: Ruleset as a JSON string. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--name TEXT Flag name. \[required]
--key TEXT Unique machine-readable key. \[required]
--description TEXT Flag description.
--status TEXT Initial status (enabled, disabled,
archived).
--tags TEXT Comma-separated tags.
--serving-method TEXT Serving method (client, server,
remote_or_local, remote_only).
--ruleset TEXT Ruleset as JSON string.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
delete¶
Delete a feature flag.
Permanently deletes a feature flag by ID. This action cannot be undone.
Args: ctx: Typer context with global options. flag_id: Feature flag identifier.
Usage:
Options:
duplicate¶
Duplicate an existing feature flag.
Creates a copy of the specified feature flag with a new ID.
Args: ctx: Typer context with global options. flag_id: Feature flag identifier. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
FLAG_ID Feature flag ID. \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
get¶
Get a single feature flag by ID.
Retrieves the full feature flag object including configuration, metadata, and permissions.
Args: ctx: Typer context with global options. flag_id: Feature flag identifier. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
FLAG_ID Feature flag ID. \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
history¶
View change history for a feature flag.
Retrieves the paginated change history for the specified feature flag, including status changes, rule updates, etc.
Args: ctx: Typer context with global options. flag_id: Feature flag identifier. page: Pagination cursor for next page. page_size: Number of results per page. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
FLAG_ID Feature flag ID. \[required]
--page TEXT Pagination cursor.
--page-size INTEGER Results per page.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
limits¶
View account-level feature flag usage and limits.
Retrieves the current flag usage, maximum limit, trial status, and contract status for the account.
Args: ctx: Typer context with global options. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
list¶
List feature flags for the current project.
Retrieves all feature flags visible to the authenticated user. By default, archived flags are excluded.
Args: ctx: Typer context with global options. include_archived: Whether to include archived flags. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--include-archived Include archived flags in the listing.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
restore¶
Restore an archived feature flag.
Restores a previously archived feature flag, returning it to its prior state.
Args: ctx: Typer context with global options. flag_id: Feature flag identifier. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
FLAG_ID Feature flag ID. \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
set-test-users¶
Set test user variant overrides on a feature flag.
Assigns specific users to specific variants for testing purposes. The users parameter is a JSON mapping of variant keys to user distinct IDs.
Args: ctx: Typer context with global options. flag_id: Feature flag identifier. users: Test users as a JSON string mapping variant keys to user IDs.
Usage:
Options:
FLAG_ID Feature flag ID. \[required]
--users TEXT Test users as JSON string (e.g. '{"on": "user-1", "off":
"user-2"}'). \[required]
update¶
Update an existing feature flag (full replacement).
Performs a full replacement of the feature flag. All required fields (name, key, status, ruleset) must be provided.
Args: ctx: Typer context with global options. flag_id: Feature flag identifier. name: Flag name (required). key: Unique machine-readable key (required). status: Target status (required). ruleset: Complete ruleset as JSON string (required). description: Optional flag description. tags: Comma-separated tags. context: Optional flag context identifier. serving_method: Serving method. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
FLAG_ID Feature flag ID. \[required]
--name TEXT Flag name (required for full replacement).
\[required]
--key TEXT Unique machine-readable key (required).
\[required]
--status TEXT Target status (enabled, disabled, archived)
(required). \[required]
--ruleset TEXT Complete ruleset as JSON string (required).
\[required]
--description TEXT Flag description.
--tags TEXT Comma-separated tags.
--context TEXT Flag context identifier (e.g.
'distinct_id').
--serving-method TEXT Serving method (client, server,
remote_or_local, remote_only).
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
inspect¶
Inspect Mixpanel project schema.
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 [json|jsonl|table|csv|plain]
Output format. \[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 [json|jsonl|table|csv|plain]
Output format. \[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 [json|jsonl|table|csv|plain]
Output format. \[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 [json|jsonl|table|csv|plain]
Output format. \[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 [json|jsonl|table|csv|plain]
Output format. \[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 [json|jsonl|table|csv|plain]
Output format. \[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 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 [json|jsonl|table|csv|plain]
Output format. \[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 [json|jsonl|table|csv|plain]
Output format. \[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 [json|jsonl|table|csv|plain]
Output format. \[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 [json|jsonl|table|csv|plain]
Output format. \[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 [json|jsonl|table|csv|plain]
Output format. \[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 [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
subproperties¶
Discover subproperties of a list-of-object event property.
Samples raw values via the Mixpanel property-values endpoint, parses
each as JSON, and infers a scalar type per discovered subproperty.
Use this when an event property like cart is a list of objects
(e.g. [{"Brand": "nike", "Price": 50}, ...]) — the discovered
subproperty names and types feed directly into Filter.list_contains
and GroupBy.list_item (Python API).
Output Structure (JSON):
[
{"name": "Brand", "type": "string", "sample_values": ["nike", "puma"]},
{"name": "Category", "type": "string", "sample_values": ["hats", "jeans"]},
{"name": "Price", "type": "number", "sample_values": [51, 87, 102]}
]
Examples:
mp inspect subproperties -p cart -e "Cart Viewed"
mp inspect subproperties -p line_items -e Purchase --sample-size 100
mp inspect subproperties -p cart -e "Cart Viewed" --format table
jq Examples:
--jq '[.[] | select(.type == "number")]' # Numeric subproperties only
--jq '[.[].name]' # Subproperty names only
--jq '.[] | select(.name == "Brand")' # Find a specific subproperty
--jq '[.[] | {name, type}]' # Drop sample_values
Usage:
Options:
-p, --property TEXT List-of-object property name. \[required]
-e, --event TEXT Event name (strongly recommended).
-s, --sample-size INTEGER Number of raw values to sample. \[default:
50]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[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 [json|jsonl|table|csv|plain]
Output format. \[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 [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
lexicon¶
Manage Lexicon data definitions.
Usage:
anomalies¶
Manage data volume anomalies.
Usage:
bulk-update¶
Bulk-update data volume anomalies.
Accepts a JSON string with parameters for updating multiple anomalies at once.
Args: ctx: Typer context with global options. body: JSON string containing the bulk update payload. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--body TEXT Bulk anomaly update payload as JSON string.
\[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
list¶
List data volume anomalies.
Retrieves anomalies detected in data volume patterns. Optionally filter by status or limit the number of results.
Args: ctx: Typer context with global options. status: Optional status filter (e.g. 'open', 'dismissed'). limit: Optional maximum number of results. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--status TEXT Filter by anomaly status.
--limit INTEGER Maximum number of anomalies to return.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
update¶
Update a single data volume anomaly.
Changes the status and classification of a specific anomaly by ID.
Args: ctx: Typer context with global options. id: Anomaly ID (integer). status: New status value. anomaly_class: Anomaly classification string. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--id INTEGER Anomaly ID to update. \[required]
--status TEXT New anomaly status. \[required]
--anomaly-class TEXT Anomaly classification. \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
audit¶
Run schema audit to find violations.
Audits the project schema for violations such as unexpected events,
missing properties, or unexpected property types. Use --events-only
for a faster, event-scoped audit.
Args: ctx: Typer context with global options. events_only: If True, audit events only instead of full schema. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--events-only Run audit for events only (faster, fewer
results).
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
deletion-requests¶
Manage event deletion requests.
Usage:
cancel¶
Cancel a pending deletion request.
Cancels a previously submitted deletion request by its ID. Only pending requests can be cancelled.
Args: ctx: Typer context with global options. id: Deletion request ID (positional argument). format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
ID Deletion request ID to cancel. \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
create¶
Create an event deletion request.
Submits a request to delete event data matching the specified event name, date range, and optional property filters.
Args: ctx: Typer context with global options. event_name: Event name to delete data for. from_date: Start date in YYYY-MM-DD format. to_date: End date in YYYY-MM-DD format. filters: Optional JSON string with property filters. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--event-name TEXT Event name to delete data for. \[required]
--from-date TEXT Start date (YYYY-MM-DD). \[required]
--to-date TEXT End date (YYYY-MM-DD). \[required]
--filters TEXT Optional property filters as JSON string.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
list¶
List event deletion requests.
Retrieves all event deletion requests for the project.
Args: ctx: Typer context with global options. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
preview¶
Preview deletion filter results.
Shows what data would be affected by a deletion request without actually creating one. Useful for validating filters before submitting a real deletion request.
Args: ctx: Typer context with global options. event_name: Event name to preview deletion for. from_date: Start date in YYYY-MM-DD format. to_date: End date in YYYY-MM-DD format. filters: Optional JSON string with property filters. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--event-name TEXT Event name to preview deletion for.
\[required]
--from-date TEXT Start date (YYYY-MM-DD). \[required]
--to-date TEXT End date (YYYY-MM-DD). \[required]
--filters TEXT Optional property filters as JSON string.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
enforcement¶
Manage schema enforcement.
Usage:
delete¶
Delete schema enforcement settings.
Removes all schema enforcement configuration for the project. This action cannot be undone.
Args: ctx: Typer context with global options.
Usage:
get¶
Get schema enforcement settings.
Retrieves the current schema enforcement configuration for the project.
Use --fields to limit the response to specific fields.
Args: ctx: Typer context with global options. fields: Optional comma-separated field names to include. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--fields TEXT Comma-separated fields to include.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
init¶
Initialize schema enforcement.
Sets up schema enforcement for the project with the given rule event as the initial enforcement target.
Args: ctx: Typer context with global options. rule_event: Enforcement action ("Warn and Accept", "Warn and Hide", or "Warn and Drop"). format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--rule-event TEXT Enforcement action (e.g. 'Warn and Accept',
'Warn and Hide', 'Warn and Drop').
\[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
replace¶
Replace schema enforcement settings (PUT semantics).
Replaces the entire schema enforcement configuration with the provided payload. All existing settings will be overwritten.
Args: ctx: Typer context with global options. body: JSON string containing the full replacement payload. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--body TEXT Schema enforcement replacement payload as
JSON string. \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
update¶
Update schema enforcement settings (PATCH semantics).
Applies a partial update to the schema enforcement configuration. Accepts a JSON string with the fields to update.
Args: ctx: Typer context with global options. body: JSON string containing the update payload. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--body TEXT Schema enforcement update payload as JSON
string. \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
event-history¶
Get change history for an event definition.
Retrieves a chronological list of changes made to the event definition over time.
Args: ctx: Typer context with global options. event_name: Event name. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--event-name TEXT Event name to get history for. \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
events¶
Manage event definitions.
Usage:
bulk-update¶
Bulk-update event definitions.
Accepts a JSON string with a list of event updates. Each entry
should include name and any fields to change.
Args: ctx: Typer context with global options. data: JSON string containing bulk update payload. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--data TEXT Bulk update payload as JSON string (list of
event updates). \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
delete¶
Delete an event definition from Lexicon.
Permanently removes the event definition. This action cannot be undone.
Args: ctx: Typer context with global options. name: Event name to delete.
Usage:
Options:
get¶
Get event definitions by name.
Retrieves metadata (description, tags, visibility, etc.) for the specified events from the Mixpanel Lexicon.
Args: ctx: Typer context with global options. names: Comma-separated event names. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--names TEXT Comma-separated event names. \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
update¶
Update an event definition (PATCH semantics).
Only fields provided will be updated. Use boolean flags like
--hidden/--no-hidden to toggle visibility.
Args: ctx: Typer context with global options. name: Event name to update. hidden: Whether to hide the event. dropped: Whether to drop event data at ingestion. verified: Whether to mark the event as verified. description: New description text. tags: Comma-separated tag names to assign. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--name TEXT Event name to update. \[required]
--hidden / --no-hidden Hide or unhide event.
--dropped / --no-dropped Drop or undrop event data.
--verified / --no-verified Mark event as verified or unverified.
--description TEXT New event description.
--tags TEXT Comma-separated tag names to assign.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
export¶
Export Lexicon data definitions.
Exports event and property definitions, optionally filtered by type.
Args: ctx: Typer context with global options. types: Comma-separated export types to include. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--types TEXT Comma-separated export types (events,
event_properties, user_properties).
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
properties¶
Manage property definitions.
Usage:
bulk-update¶
Bulk-update property definitions.
Accepts a JSON string with a list of property updates. Each entry
should include name and any fields to change.
Args: ctx: Typer context with global options. data: JSON string containing bulk update payload. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--data TEXT Bulk update payload as JSON string (list of
property updates). \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
get¶
Get property definitions by name.
Retrieves metadata (description, tags, visibility, etc.) for the specified properties from the Mixpanel Lexicon.
Args: ctx: Typer context with global options. names: Comma-separated property names. resource_type: Optional resource type filter. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--names TEXT Comma-separated property names. \[required]
--resource-type TEXT Resource type filter (event, user,
groupprofile).
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
update¶
Update a property definition (PATCH semantics).
Only fields provided will be updated. Use boolean flags like
--hidden/--no-hidden to toggle visibility.
Args: ctx: Typer context with global options. name: Property name to update. hidden: Whether to hide the property. dropped: Whether to drop property data. sensitive: Whether to mark the property as PII sensitive. description: New description text. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--name TEXT Property name to update. \[required]
--hidden / --no-hidden Hide or unhide property.
--dropped / --no-dropped Drop or undrop property data.
--sensitive / --no-sensitive Mark property as PII sensitive.
--description TEXT New property description.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
property-history¶
Get change history for a property definition.
Retrieves a chronological list of changes made to the property definition over time.
Args: ctx: Typer context with global options. property_name: Property name. entity_type: Entity type (event, user, group). format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--property-name TEXT Property name to get history for.
\[required]
--entity-type TEXT Entity type (event, user, group).
\[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
tags¶
Manage Lexicon tags.
Usage:
create¶
Create a new Lexicon tag.
Creates a tag that can be assigned to event and property definitions.
Args: ctx: Typer context with global options. name: Tag name to create. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--name TEXT Tag name to create. \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
delete¶
Delete a Lexicon tag by name.
Permanently removes the tag. This action cannot be undone.
Args: ctx: Typer context with global options. name: Tag name to delete.
Usage:
Options:
list¶
List all Lexicon tags.
Retrieves all tags available for categorizing event and property definitions.
Args: ctx: Typer context with global options. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
update¶
Update an existing Lexicon tag.
Renames an existing tag by its ID.
Args: ctx: Typer context with global options. id: Tag ID (integer). name: New tag name. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--id INTEGER Tag ID to update. \[required]
--name TEXT New tag name. \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
tracking-metadata¶
Get tracking metadata for an event.
Retrieves information about how an event is being tracked (sources, SDKs, volume, etc.).
Args: ctx: Typer context with global options. event_name: Event name. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--event-name TEXT Event name to get metadata for. \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
lookup-tables¶
Manage lookup tables.
Usage:
delete¶
Delete one or more lookup tables.
Permanently deletes lookup tables by their data group IDs. Provide IDs as a comma-separated string.
Args: ctx: Typer context with global options. data_group_ids: Comma-separated data group IDs.
Usage:
Options:
download¶
Download lookup table data as CSV.
Downloads the lookup table data. If --output is specified, writes the CSV to the given file path. Otherwise, prints CSV to stdout.
Args: ctx: Typer context with global options. data_group_id: Data group ID of the lookup table. file_name: Optional file name filter. limit: Optional row limit. output: Output file path.
Usage:
Options:
--data-group-id INTEGER Data group ID (required). \[required]
--file-name TEXT Optional file name filter.
--limit INTEGER Optional row limit.
--output TEXT Output file path (writes CSV to file).
download-url¶
Get a signed download URL for a lookup table.
Returns a signed URL that can be used to download the lookup table data directly.
Args: ctx: Typer context with global options. data_group_id: Data group ID of the lookup table. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--data-group-id INTEGER Data group ID (required). \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
list¶
List lookup tables for the current project.
Retrieves all lookup tables, optionally filtered by data group ID.
Args: ctx: Typer context with global options. data_group_id: Optional filter by data group ID. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--data-group-id INTEGER Filter by data group ID.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
update¶
Update a lookup table.
Updates the name of an existing lookup table identified by its data group ID.
Args: ctx: Typer context with global options. data_group_id: Data group ID of the lookup table. name: New table name. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--data-group-id INTEGER Data group ID (required). \[required]
--name TEXT New table name (required). \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
upload¶
Upload a CSV file as a new lookup table.
Performs a 3-step upload: obtains a signed URL, uploads the CSV, then registers the table.
Args: ctx: Typer context with global options. name: Table name. file: Path to the local CSV file. data_group_id: Data group ID for replacing an existing table. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--name TEXT Table name (required). \[required]
--file TEXT Path to CSV file to upload (required).
\[required]
--data-group-id INTEGER Data group ID (for replacing an existing
table).
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
upload-url¶
Get a signed URL for uploading lookup table data.
Returns a signed upload URL, path, and key that can be used to upload data directly.
Args: ctx: Typer context with global options. content_type: MIME type of the file to upload. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--content-type TEXT MIME type of the file. \[default: text/csv]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
project¶
Active project.
Usage:
list¶
List projects accessible by the active account.
Always enumerates from /me (24h cached). The active project is
marked. --refresh bypasses the local cache and refetches. Works
with only authentication configured — no project axis required
(FR-047).
Args:
ctx: Typer context.
refresh: Bypass the local /me cache and refetch.
format: Output format (table / json / jsonl).
Usage:
Options:
--refresh Bypass the local /me cache and refetch.
-f, --format TEXT Output format: table | json | jsonl. \[default: table]
show¶
Show the currently active project (active account's default_project).
Args: ctx: Typer context.
Usage:
use¶
Update the active account's default_project.
Project lives on the account, not in [active]. This command is
equivalent to mp account update <active-account> --project ID.
Args: ctx: Typer context. project_id: Mixpanel project ID (numeric string).
Usage:
Options:
query¶
Query Mixpanel 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 [json|jsonl|table|csv|plain]
Output format. \[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 [json|jsonl|table|csv|plain]
Output format. \[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 [json|jsonl|table|csv|plain]
Output format. \[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 [json|jsonl|table|csv|plain]
Output format. \[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 [json|jsonl|table|csv|plain]
Output format. \[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 [json|jsonl|table|csv|plain]
Output format. \[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 [json|jsonl|table|csv|plain]
Output format. \[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 [json|jsonl|table|csv|plain]
Output format. \[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 [json|jsonl|table|csv|plain]
Output format. \[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 [json|jsonl|table|csv|plain]
Output format. \[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 [json|jsonl|table|csv|plain]
Output format. \[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 [json|jsonl|table|csv|plain]
Output format. \[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 [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
reports¶
Manage Mixpanel reports (bookmarks).
Usage:
bulk-delete¶
Delete multiple bookmarks at once.
Permanently removes all specified bookmarks from the project.
Args: ctx: Typer context with global options. ids: Comma-separated bookmark IDs to delete.
Example:
Usage:
Options:
bulk-update¶
Update multiple bookmarks at once.
Accepts a JSON array of update entries. Each entry must include
an id field and any fields to update (e.g., name).
Args: ctx: Typer context with global options. entries: JSON string containing a list of update entries.
Example:
Usage:
Options:
create¶
Create a new bookmark (saved report).
Creates a bookmark in the Mixpanel App API with the given name, type, and query parameters.
Args:
ctx: Typer context with global options.
name: Name for the new report.
bookmark_type: Report type (e.g., "insights", "funnels").
params: Report parameters as a JSON string.
description: Optional description for the report.
dashboard_id: Optional dashboard ID to add the report to.
format: Output format (json, jsonl, table, csv, plain).
jq_filter: Optional jq filter expression for JSON output.
Example:
mp reports create --name "Signup Funnel" --type funnels \
--params '{"events": [{"event": "Signup"}]}'
Usage:
Options:
-n, --name TEXT Name for the new report. \[required]
-t, --type TEXT Report type (e.g., insights, funnels).
\[required]
-p, --params TEXT Report parameters as a JSON string.
\[required]
-d, --description TEXT Optional description.
--dashboard-id INTEGER Dashboard ID to add the report to.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
dashboard-ids¶
Get dashboard IDs containing a bookmark.
Returns a list of dashboard IDs that contain the specified
bookmark. Uses the get_bookmark_dashboard_ids workspace method.
Args: ctx: Typer context with global options. bookmark_id: The bookmark identifier. format: Output format (json, jsonl, table, csv, plain). jq_filter: Optional jq filter expression for JSON output.
Example:
Usage:
Options:
BOOKMARK_ID Bookmark ID to look up. \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
delete¶
Delete a bookmark.
Permanently removes the specified bookmark from the project.
Args: ctx: Typer context with global options. bookmark_id: The bookmark identifier.
Example:
Usage:
Options:
get¶
Get a single bookmark by ID.
Retrieves the full bookmark object from the Mixpanel App API.
Args: ctx: Typer context with global options. bookmark_id: The bookmark identifier. format: Output format (json, jsonl, table, csv, plain). jq_filter: Optional jq filter expression for JSON output.
Example:
Usage:
Options:
BOOKMARK_ID Bookmark ID to retrieve. \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
history¶
Get change history for a bookmark.
Returns a paginated list of changes made to the specified bookmark, including who made the change and when.
Args: ctx: Typer context with global options. bookmark_id: The bookmark identifier. cursor: Opaque pagination cursor for fetching subsequent pages. page_size: Maximum number of entries per page. format: Output format (json, jsonl, table, csv, plain). jq_filter: Optional jq filter expression for JSON output.
Example:
mp reports history 12345
mp reports history 12345 --page-size 10
mp reports history 12345 --cursor "abc123"
Usage:
Options:
BOOKMARK_ID Bookmark ID to get history for. \[required]
--cursor TEXT Pagination cursor for next page.
--page-size INTEGER Maximum entries per page.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
linked-dashboards¶
Get dashboard IDs linked to a bookmark.
Returns a list of dashboard IDs that reference the specified
bookmark via the bookmark_linked_dashboard_ids API.
Args: ctx: Typer context with global options. bookmark_id: The bookmark identifier. format: Output format (json, jsonl, table, csv, plain). jq_filter: Optional jq filter expression for JSON output.
Example:
Usage:
Options:
BOOKMARK_ID Bookmark ID to look up. \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
list¶
List bookmarks/reports with optional filters.
Retrieves bookmarks from the Mixpanel App API. Optionally filter by report type or specific IDs.
Args:
ctx: Typer context with global options.
bookmark_type: Optional report type filter (e.g., "funnels").
ids: Comma-separated bookmark IDs to filter by.
format: Output format (json, jsonl, table, csv, plain).
jq_filter: Optional jq filter expression for JSON output.
Example:
Usage:
Options:
-t, --type TEXT Filter by bookmark type (e.g., insights,
funnels, flows, retention).
--ids TEXT Comma-separated list of bookmark IDs to
retrieve.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
update¶
Update an existing bookmark.
Patches the specified bookmark with the provided fields. Only supplied fields are updated; omitted fields remain unchanged.
Args: ctx: Typer context with global options. bookmark_id: The bookmark identifier. name: New name for the report. params: Updated report parameters as a JSON string. description: Updated description. format: Output format (json, jsonl, table, csv, plain). jq_filter: Optional jq filter expression for JSON output.
Example:
mp reports update 12345 --name "Renamed Report"
mp reports update 12345 --params '{"events": [{"event": "Login"}]}'
Usage:
Options:
BOOKMARK_ID Bookmark ID to update. \[required]
-n, --name TEXT New name for the report.
-p, --params TEXT Updated report parameters as a JSON string.
-d, --description TEXT Updated description.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
schemas¶
Manage schema registry definitions.
Usage:
create¶
Create a single schema entry.
Creates a new schema definition for the specified entity type and name.
Args: ctx: Typer context with global options. entity_type: Entity type (event, custom_event, or profile). entity_name: Entity name for the schema. schema_json: Schema definition as a JSON string. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--entity-type TEXT Entity type (event, custom_event, or
profile). \[required]
--entity-name TEXT Entity name for the schema. \[required]
--schema-json TEXT Schema definition as a JSON string.
\[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
create-bulk¶
Bulk create schema entries.
Creates multiple schema entries in a single request. Optionally truncates existing schemas before creating.
Args: ctx: Typer context with global options. entries: JSON array of schema entries. truncate: Whether to truncate existing schemas before creating. entity_type: Entity type filter for truncation scope. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--entries TEXT JSON array of schema entries for bulk
creation. \[required]
--truncate / --no-truncate Truncate existing schemas before creating.
\[default: no-truncate]
--entity-type TEXT Entity type filter for truncation scope.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
delete¶
Delete schema entries.
Deletes schema entries, optionally filtered by entity type and/or entity name. Without filters, deletes all schemas.
Args: ctx: Typer context with global options. entity_type: Optional entity type filter for deletion. entity_name: Optional entity name filter for deletion. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--entity-type TEXT Entity type filter for deletion.
--entity-name TEXT Entity name filter for deletion.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
list¶
List schema registry entries.
Retrieves all schema entries, optionally filtered by entity type.
Args: ctx: Typer context with global options. entity_type: Optional entity type filter. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--entity-type TEXT Filter by entity type (event, custom_event,
or profile).
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
update¶
Update a single schema entry (merge semantics).
Updates an existing schema definition. Fields provided in the JSON are merged with the existing schema.
Args: ctx: Typer context with global options. entity_type: Entity type (event, custom_event, or profile). entity_name: Entity name for the schema. schema_json: Schema updates as a JSON string. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--entity-type TEXT Entity type (event, custom_event, or
profile). \[required]
--entity-name TEXT Entity name for the schema. \[required]
--schema-json TEXT Schema updates as a JSON string (merge
semantics). \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
update-bulk¶
Bulk update schema entries.
Updates multiple schema entries in a single request.
Args: ctx: Typer context with global options. entries: JSON array of schema entries for bulk update. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--entries TEXT JSON array of schema entries for bulk
update. \[required]
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
session¶
Show / update the active session.
Usage:
Options:
--bridge Show bridge file source (Cowork).
-f, --format TEXT Output format: text | json \[default: text]
target¶
Manage saved target triples.
Usage:
add¶
Add a new saved target triple.
Args: ctx: Typer context. name: Target name (must not already exist). account: Referenced account (must exist). project: Project ID (digit string). workspace: Optional positive workspace ID.
Usage:
Options:
NAME Target name (block key). \[required]
-a, --account TEXT Referenced account name. \[required]
-p, --project TEXT Project ID (digit string). \[required]
-w, --workspace INTEGER Optional workspace ID.
list¶
List all configured targets.
Args: ctx: Typer context. format: Output format.
Usage:
Options:
remove¶
Remove a target block.
Args: ctx: Typer context. name: Target name. yes: Skip confirmation prompt.
Usage:
Options:
show¶
Show a single target's details.
Args: ctx: Typer context. name: Target name. format: Output format.
Usage:
Options:
use¶
Apply the target — write all three axes to [active] atomically.
Also updates the target account's default_project to the target's
project, so a fresh Workspace() reproduces the same session.
Args: ctx: Typer context. name: Target to apply.
Usage:
Options:
webhooks¶
Manage project webhooks.
Usage:
create¶
Create a new webhook.
Creates a webhook with the specified name and URL. Optional authentication parameters can be provided for secured endpoints.
Args: ctx: Typer context with global options. name: Webhook name (required). url: Webhook URL (required). auth_type: Authentication type (e.g. 'basic'). username: Basic auth username. password: Basic auth password. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--name TEXT Webhook name. \[required]
--url TEXT Webhook URL. \[required]
--auth-type TEXT Auth type (e.g. 'basic').
--username TEXT Basic auth username.
--password TEXT Basic auth password.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
delete¶
Delete a webhook.
Permanently deletes a webhook by ID. This action cannot be undone.
Args: ctx: Typer context with global options. webhook_id: Webhook UUID string.
Usage:
Options:
list¶
List all project webhooks.
Retrieves all webhooks configured for the current project.
Args: ctx: Typer context with global options. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
test¶
Test webhook connectivity.
Sends a test request to the specified URL and reports the result.
Args: ctx: Typer context with global options. url: Webhook URL to test (required). name: Optional webhook name. auth_type: Authentication type. username: Basic auth username. password: Basic auth password. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
--url TEXT Webhook URL to test. \[required]
--name TEXT Webhook name.
--auth-type TEXT Auth type.
--username TEXT Basic auth username.
--password TEXT Basic auth password.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
update¶
Update an existing webhook.
Updates webhook fields using PATCH semantics. Only provided fields are modified.
Args: ctx: Typer context with global options. webhook_id: Webhook UUID string. name: New webhook name. url: New webhook URL. auth_type: New authentication type. username: New basic auth username. password: New basic auth password. enabled: Enable or disable the webhook. format: Output format. jq_filter: Optional jq filter expression.
Usage:
Options:
WEBHOOK_ID Webhook ID (UUID). \[required]
--name TEXT New webhook name.
--url TEXT New webhook URL.
--auth-type TEXT New auth type.
--username TEXT New basic auth username.
--password TEXT New basic auth password.
--enabled / --no-enabled Enable or disable webhook.
-f, --format [json|jsonl|table|csv|plain]
Output format. \[default: json]
--jq TEXT Apply jq filter to JSON output (requires
--format json or jsonl).
workspace¶
Active workspace.
Usage:
list¶
List workspaces in the current (or specified) project via /me.
Constructs a short-lived :class:Workspace against the resolved
session, then pulls the workspace list from the cached /me
response (24h TTL) for --project (or the active project when
--project is omitted). --refresh bypasses the cache.
Args:
ctx: Typer context.
project: Project to query (defaults to the active project).
refresh: Bypass the local /me cache and refetch.
format: Output format (table / json / jsonl).
Usage:
Options:
-p, --project TEXT Project ID (defaults to active project).
--refresh Bypass the local /me cache (FR-047).
-f, --format TEXT Output format: table | json | jsonl. \[default: table]
show¶
Show the currently active workspace.
When the active workspace is unset, prints
(workspace will be auto-resolved on first use).
Args: ctx: Typer context.
Usage:
use¶
Set the active workspace ID.
Args: ctx: Typer context. workspace_id: Mixpanel workspace ID (positive int).
Usage:
Options: