mpql

A command-line tool to execute MixPanel Query API requests. Designed for both human users and AI agents.

Installation

gem install mpql

Configuration

Create ~/.mpql.yml:

username: your-service-account-username
secret: your-service-account-secret

Or use environment variables:

MIXPANEL_USERNAME=your-service--username
MIXPANEL_SECRET=your-service--secret

Usage

Segmentation

mpql segmentation --project-id 123456 --event "Signed Up" --from 7d --to today
mpql segmentation --project-id 123456 --event "Page View" --from 2026-03-01 --to 2026-03-09 --on "properties.$browser" --unit day
mpql segmentation --project-id 123456 --event "Purchase" --from 1m --to today --type unique --format tsv

Funnels

mpql funnels --project-id 123456 --funnel-id 12345 --from 7d --to today
mpql funnels --project-id 123456 --funnel-id 12345 --from 2026-03-01 --to 2026-03-09 --on "properties.$os"

Retention

mpql retention --project-id 123456 --from 30d --to today
mpql retention --project-id 123456 --from 2026-02-01 --to 2026-03-09 --born-event "Signed Up" --event "Login"

Insights

mpql insights --project-id 123456 --bookmark-id 67890

Cohorts

mpql cohorts --project-id 123456
mpql cohorts --project-id 123456 --format table

Export (Raw Event Data)

mpql export --project-id 123456 --event "ScreenView" --from 7d --to today
mpql export --project-id 123456 --event "Signed Up" --from 2026-03-01 --to 2026-03-09

Engage (User Profiles)

mpql engage --project-id 123456
mpql engage --project-id 123456 --where 'properties["$email"] == "[email protected]"'
mpql engage --project-id 123456 --distinct-id "user123"
mpql engage --project-id 123456 --distinct-id "user123" "user456" "user789"

Date Formats

  • yyyy-mm-dd (e.g., 2026-03-01)
  • today, yesterday
  • Nd - N days ago (e.g., 7d)
  • Nw - N weeks ago (e.g., 2w)
  • Nm - N months ago (e.g., 1m)

Output Formats

  • --format json (default) - JSON output
  • --format tsv - Tab-separated values
  • --format table - ASCII table
  • --raw - Raw JSON without pretty-printing

Global Options

  • --project-id - MixPanel project ID (required)
  • --region - MixPanel region (us, eu, in). Defaults to us

Release

  1. Update the version number in lib/mpql/version.rb
  2. Commit the changes
  3. Run rake release

This will create a git tag, build the gem, and push it to rubygems.org.

License

MIT License. See LICENSE.txt for details.