Welcome to Mixpanel

This is the official Mixpanel client library for Python.

Mixpanel client libraries allow for tracking events and setting properties on People Analytics profiles from your server-side projects. This is the API documentation; you may also be interested in the higher-level usage documentation. If your users are interacting with your application via the web, you may also be interested in our JavaScript library.

Mixpanel is the primary class for tracking events and sending People Analytics updates. Consumer and BufferedConsumer allow callers to customize the IO characteristics of their tracking.

Primary interface

class mixpanel.Mixpanel(token, consumer=None, serializer=<class 'mixpanel.DatetimeSerializer'>)

Instances of Mixpanel are used for all events and profile updates.

Parameters:
  • token (str) – your project’s Mixpanel token
  • consumer – can be used to alter the behavior of tracking (default Consumer)
  • serializer (json.JSONEncoder) – a JSONEncoder subclass used to handle JSON serialization (default DatetimeSerializer)

See Built-in consumers for details about the consumer interface.

New in version 4.2.0: The serializer parameter.

track(distinct_id, event_name, properties=None, meta=None)

Record an event.

Parameters:
  • distinct_id (str) – identifies the user triggering the event
  • event_name (str) – a name describing the event
  • properties (dict) – additional data to record; keys should be strings, and values should be strings, numbers, or booleans
  • meta (dict) – overrides Mixpanel special properties

properties should describe the circumstances of the event, or aspects of the source or user associated with it. meta is used (rarely) to override special values sent in the event object.

import_data(api_key, distinct_id, event_name, timestamp, properties=None, meta=None)

Record an event that occured more than 5 days in the past.

Parameters:
  • api_key (str) – your Mixpanel project’s API key
  • distinct_id (str) – identifies the user triggering the event
  • event_name (str) – a name describing the event
  • timestamp (int) – UTC seconds since epoch
  • properties (dict) – additional data to record; keys should be strings, and values should be strings, numbers, or booleans
  • meta (dict) – overrides Mixpanel special properties

To avoid accidentally recording invalid events, the Mixpanel API’s track endpoint disallows events that occurred too long ago. This method can be used to import such events. See our online documentation for more details.

alias(alias_id, original, meta=None)

Apply a custom alias to a people record.

Parameters:
  • alias_id (str) – the new distinct_id
  • original (str) – the previous distinct_id
  • meta (dict) – overrides Mixpanel special properties

Immediately creates a one-way mapping between two distinct_ids. Events triggered by the new id will be associated with the existing user’s profile and behavior. See our online documentation for more details.

Note

Calling this method always results in a synchronous HTTP request to Mixpanel servers, regardless of any custom consumer.

people_set(distinct_id, properties, meta=None)

Set properties of a people record.

Parameters:
  • distinct_id (str) – the profile to update
  • properties (dict) – properties to set
  • meta (dict) – overrides Mixpanel special properties

If the profile does not exist, creates a new profile with these properties.

people_set_once(distinct_id, properties, meta=None)

Set properties of a people record if they are not already set.

Parameters:
  • distinct_id (str) – the profile to update
  • properties (dict) – properties to set

Any properties that already exist on the profile will not be overwritten. If the profile does not exist, creates a new profile with these properties.

people_increment(distinct_id, properties, meta=None)

Increment/decrement numerical properties of a people record.

Parameters:
  • distinct_id (str) – the profile to update
  • properties (dict) – properties to increment/decrement; values should be numeric

Adds numerical values to properties of a people record. Nonexistent properties on the record default to zero. Negative values in properties will decrement the given property.

people_append(distinct_id, properties, meta=None)

Append to the list associated with a property.

Parameters:
  • distinct_id (str) – the profile to update
  • properties (dict) – properties to append

Adds items to list-style properties of a people record. Appending to nonexistent properties results in a list with a single element. For example:

mp.people_append('123', {'Items': 'Super Arm'})
people_union(distinct_id, properties, meta=None)

Merge the values of a list associated with a property.

Parameters:
  • distinct_id (str) – the profile to update
  • properties (dict) – properties to merge

Merges list values in properties with existing list-style properties of a people record. Duplicate values are ignored. For example:

mp.people_union('123', {'Items': ['Super Arm', 'Fire Storm']})
people_unset(distinct_id, properties, meta=None)

Permanently remove properties from a people record.

Parameters:
  • distinct_id (str) – the profile to update
  • properties (list) – property names to remove
people_delete(distinct_id, meta=None)

Permanently delete a people record.

Parameters:distinct_id (str) – the profile to delete
people_track_charge(distinct_id, amount, properties=None, meta=None)

Track a charge on a people record.

Parameters:
  • distinct_id (str) – the profile with which to associate the charge
  • amount (numeric) – number of dollars charged
  • properties (dict) – extra properties related to the transaction

Record that you have charged the current user a certain amount of money. Charges recorded with this way will appear in the Mixpanel revenue report.

people_clear_charges(distinct_id, meta=None)

Permanently clear all charges on a people record.

Parameters:distinct_id (str) – the profile whose charges will be cleared
people_update(message, meta=None)

Send a generic update to Mixpanel people analytics.

Parameters:message (dict) – the message to send

Callers are responsible for formatting the update message as documented in the Mixpanel HTTP specification. This method may be useful if you want to use very new or experimental features of people analytics, but please use the other people_* methods where possible.

Built-in consumers

A consumer is any object with a send method which takes two arguments: a string endpoint name and a JSON-encoded message. send is responsible for appropriately encoding the message and sending it to the named Mixpanel API endpoint.

Mixpanel instances call their consumer’s send method at the end of each of their own method calls, after building the JSON message.

class mixpanel.Consumer(events_url=None, people_url=None, import_url=None, request_timeout=None)

A consumer that sends an HTTP request directly to the Mixpanel service, one per call to send().

Parameters:
  • events_url (str) – override the default events API endpoint
  • people_url (str) – override the default people API endpoint
  • import_url (str) – override the default import API endpoint
  • request_timeout (int) – connection timeout in seconds
send(endpoint, json_message, api_key=None)

Immediately record an event or a profile update.

Parameters:
  • endpoint (“events” | “people” | “imports”) – the Mixpanel API endpoint appropriate for the message
  • json_message (str) – a JSON message formatted for the endpoint
  • api_key (str) – your Mixpanel project’s API key
Raises MixpanelException:
 

if the endpoint doesn’t exist, the server is unreachable, or the message cannot be processed

class mixpanel.BufferedConsumer(max_size=50, events_url=None, people_url=None, import_url=None, request_timeout=None)

A consumer that maintains per-endpoint buffers of messages and then sends them in batches. This can save bandwidth and reduce the total amount of time required to post your events to Mixpanel.

Note

Because BufferedConsumer holds events, you need to call flush() when you’re sure you’re done sending them—for example, just before your program exits. Calls to flush() will send all remaining unsent events being held by the instance.

Parameters:
  • max_size (int) – number of send() calls for a given endpoint to buffer before flushing automatically
  • events_url (str) – override the default events API endpoint
  • people_url (str) – override the default people API endpoint
  • import_url (str) – override the default import API endpoint
  • request_timeout (int) – connection timeout in seconds
send(endpoint, json_message, api_key=None)

Record an event or profile update.

Internally, adds the message to a buffer, and then flushes the buffer if it has reached the configured maximum size. Note that exceptions raised may have been caused by a message buffered by an earlier call to send().

Parameters:
  • endpoint (“events” | “people” | “imports”) – the Mixpanel API endpoint appropriate for the message
  • json_message (str) – a JSON message formatted for the endpoint
  • api_key (str) – your Mixpanel project’s API key
Raises MixpanelException:
 

if the endpoint doesn’t exist, the server is unreachable, or any buffered message cannot be processed

New in version 4.3.2: The api_key parameter.

flush()

Immediately send all buffered messages to Mixpanel.

Raises MixpanelException:
 if the server is unreachable or any buffered message cannot be processed

Exceptions

exception mixpanel.MixpanelException

Raised by consumers when unable to send messages.

This could be caused by a network outage or interruption, or by an invalid endpoint passed to Consumer.send().