mixpanel-ruby: The official Mixpanel Ruby library

##### _September 01, 2026_ - [v3.4.0](github.com/mixpanel/mixpanel-ruby/releases/tag/v3.4.0)

mixpanel-ruby is a library for tracking events and sending Mixpanel profile updates to Mixpanel from your ruby applications.

Installation

gem install mixpanel-ruby

Getting Started

require 'mixpanel-ruby'

tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)

# Track an event on behalf of user "User1"
tracker.track('User1', 'A Mixpanel Event')

# Send an update to User1's profile
tracker.people.set('User1', {
    '$first_name' => 'David',
    '$last_name' => 'Bowie',
    'Best Album' => 'The Rise and Fall of Ziggy Stardust and the Spiders from Mars'
})

The primary class you will use to track events is Mixpanel::Tracker. An instance of Mixpanel::Tracker is enough to send events directly to Mixpanel, and get you integrated right away.

Service Account Authentication

Service accounts provide secure server-to-server authentication and are recommended over API keys for import operations and feature flags.

Which credential do I need?

Mixpanel uses different credentials for different calls, and they are not interchangeable:

Project token

Passed to Mixpanel::Tracker.new and used for track, people and groups calls. It is public (it ships in client-side code) and does not authenticate import.

Service account username and secret, plus project ID

Required for import_events (and import without an API key). Create a service account in your Mixpanel organization settings (see docs.mixpanel.com/docs/orgs-and-projects/service-accounts), then pass it to Mixpanel::Tracker.new as a Mixpanel::ServiceAccountCredentials. The project ID is shown in your project settings.

API key

The legacy credential taken by import("API_KEY", ...). It is not your project token. See “Import with API Key (deprecated)” below.

Import with Service Account (Recommended)

require 'mixpanel-ruby'

# Create service account credentials
credentials = Mixpanel::ServiceAccountCredentials.new(
    'your-service-account-username',
    'your-service-account-secret',
    'your-project-id'
)

# Pass credentials to tracker constructor
# Credentials are stored securely and never serialized to JSON
tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN, credentials: credentials)

# Import historical events using import_events (recommended)
tracker.import_events('User1', 'Past Event', {
    'time' => 1369353600,
    'Source' => 'Import'
})

# Alternative: use import() with nil as first parameter
tracker.import(nil, 'User1', 'Past Event', {
    'time' => 1369353600,
    'Source' => 'Import'
})

import_events returns true when the request completed without a Mixpanel error, and false when a Mixpanel::MixpanelError was raised. With a custom consumer block, such as a queue, true only means the handoff to that block succeeded. A false result does not always mean the event was lost: after a timeout, Mixpanel may still have stored it, so set a unique $insert_id property if you retry, and Mixpanel will drop the duplicate.

With the default error handler, a failed import also prints a warning to stderr. To handle failures yourself, for example to retry or alert, pass a Mixpanel::ErrorHandler subclass:

class ImportErrorHandler < Mixpanel::ErrorHandler
  def handle(error)
    Rails.logger.error("Mixpanel import failed: #{error.message}")
  end
end

tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN, ImportErrorHandler.new, credentials: credentials)

Import with API Key (deprecated)

Passing an API key as the first argument to import, as in tracker.import("API_KEY", ...), is deprecated, and Mixpanel’s /import endpoint may reject these requests. Use service account credentials with import_events, as shown above.

Feature Flags with Service Account

require 'mixpanel-ruby'

credentials = Mixpanel::ServiceAccountCredentials.new(
    'your-service-account-username',
    'your-service-account-secret',
    'your-project-id'
)

# Pass credentials directly to the tracker
tracker = Mixpanel::Tracker.new(
    YOUR_MIXPANEL_TOKEN,
    nil,
    credentials: credentials,
    local_flags_config: {},
    remote_flags_config: {}
)

# Use feature flags
is_enabled = tracker.remote_flags.is_enabled?('my-flag', { 'distinct_id' => 'User1' })

Additional Information

For more information please visit:

• Our Ruby API Integration page

• The usage demo

• The documentation

The official Mixpanel gem is built with simplicity and broad applicability in mind, but there are also third party Ruby libraries that can work with the library to provide useful features in common situations, and support different development points of view.

In particular, for Rails apps, the following projects are currently actively maintained:

• MetaEvents

• Mengpaneel

Changes

2.3.1

• Convert timestamps to milliseconds and update Ruby compatibility

2.3.0

• Clear submitted slices during BufferedConsumer#flush

• Groups analytics support

• use millisecond precision for time properties

2.2.2

• Add Group Analytics support with Mixpanel::Groups

2.2.1

• Fix buffer clearing on partially successful writes in BufferedConsumer.

2.2.0

• Add Mixpanel::ErrorHandler to simplify custom error handling.

• Modify Mixpanel::People#fix_property_dates to handle ActiveSupport::TimeWithZone.

• Increase open and ssl timeouts from 2s to 10s.

• Fix Doc inconsistancy: always pass token on Mixpanel::tracker.new.

2.1.0

• Add Mixpanel::Tracker#generate_tracking_url, which generates pixel tracking urls.

• Rescue JSONErrors in the consumer and raise Mixpanel::ServerError in Mixpanel::Consumer#send!.

• Make it clear how to import events with custom timestamp.

• Update dependancies in gemspec

2.0.1

• Add Deprecated version of Mixpanel::BufferedConsumer#send

2.0.0

• Raise mixpanel server and connection errors in Mixpanel::Consumer.

• All public methods in Mixpanel::Event, Mixpanel::People, and subsequently Mixpanel::Tracker rescue Mixpanel errors and return false in the case of an error, return true otherwise

• Deprecate Mixpanel::Consumer#send, replace with Mixpanel::Consumer#send!

• Require ruby version minimum of 2.0.0

1.4.0

• Allow unset to unset multiple properties

1.3.0

• Added Consumer#request method, demo with Faraday integration

1.2.0

• All objects with a “strftime” method will be formatted as dates in people updates.

1.1.0

• The default consumer now sends requests (and expects responses) in verbose, JSON mode, which may improve error reporting.

1.0.2

• Allow ip and optional_params arguments to be accepted by all Mixpanel::People methods (except #destroy_user)

1.0.1

• Compatibility with earlier versions of ruby. Library development will continue to target 1.9, so later versions may not be compatible with Ruby 1.8, but we love patches!

1.0.0

• tracker#import added

• Change to internal tracking message format. Messages written by earlier versions of the library will not work with 1.0.0 consumer classes.

• alias bugfixed

• Fixes to tests to allow for different timezones

• Support for optional/experimental people api properties in people calls