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, api_secret=None)¶

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

Parameters

api_key (str) – (DEPRECATED) 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
api_secret (str) – Your Mixpanel project’s API secret.

Important

Mixpanel’s import HTTP endpoint requires the project API secret found in your Mixpanel project’s settings. The older API key is no longer accessible in the Mixpanel UI, but will continue to work. The api_key parameter will be removed in an upcoming release of mixpanel-python.

New in version 4.8.0: The api_secret parameter.

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)¶

Creates an alias which Mixpanel will use to remap one id to another.

Parameters

alias_id (str) – A distinct_id to be merged with the original distinct_id. Each alias can only map to one distinct_id.
original (str) – A distinct_id to be merged with alias_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.

merge(api_key, distinct_id1, distinct_id2, meta=None, api_secret=None)¶

Merges the two given distinct_ids.

Parameters

api_key (str) – (DEPRECATED) Your Mixpanel project’s API key.
distinct_id1 (str) – The first distinct_id to merge.
distinct_id2 (str) – The second (other) distinct_id to merge.
meta (dict) – overrides Mixpanel special properties
api_secret (str) – Your Mixpanel project’s API secret.

Important

Mixpanel’s merge HTTP endpoint requires the project API secret found in your Mixpanel project’s settings. The older API key is no longer accessible in the Mixpanel UI, but will continue to work. The api_key parameter will be removed in an upcoming release of mixpanel-python.

New in version 4.8.0: The api_secret parameter.

See our online documentation for more details.

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_remove(distinct_id, properties, meta=None)¶

Permanently remove a value from the list associated with a property.

Parameters

distinct_id (str) – the profile to update
properties (dict) – properties to remove

Removes items from list-style properties of a people record. For example:

mp.people_remove('123', {'Items': 'Super Arm'})

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 described in the user profiles documentation. 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.

group_set(group_key, group_id, properties, meta=None)¶

Set properties of a group profile.

Parameters

group_key (str) – the group key, e.g. ‘company’
group_id (str) – the group to update
properties (dict) – properties to set
meta (dict) – overrides Mixpanel special properties. (See also Mixpanel.people_set.)

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

group_set_once(group_key, group_id, properties, meta=None)¶

Set properties of a group profile if they are not already set.

Parameters

group_key (str) – the group key, e.g. ‘company’
group_id (str) – the group 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.

group_union(group_key, group_id, properties, meta=None)¶

Merge the values of a list associated with a property.

Parameters

group_key (str) – the group key, e.g. ‘company’
group_id (str) – the group to update
properties (dict) – properties to merge

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

mp.group_union('company', 'Acme Inc.', {'Items': ['Super Arm', 'Fire Storm']})

group_unset(group_key, group_id, properties, meta=None)¶

Permanently remove properties from a group profile.

Parameters

group_key (str) – the group key, e.g. ‘company’
group_id (str) – the group to update
properties (list) – property names to remove

group_remove(group_key, group_id, properties, meta=None)¶

Permanently remove a value from the list associated with a property.

Parameters

group_key (str) – the group key, e.g. ‘company’
group_id (str) – the group to update
properties (dict) – properties to remove

Removes items from list-style properties of a group profile. For example:

mp.group_remove('company', 'Acme Inc.', {'Items': 'Super Arm'})

group_delete(group_key, group_id, meta=None)¶

Permanently delete a group profile.

Parameters

group_key (str) – the group key, e.g. ‘company’
group_id (str) – the group to delete

group_update(message, meta=None)¶

Send a generic group profile update

Parameters: message (dict) – the message to send

Callers are responsible for formatting the update message as documented in the group profiles documentation. This method may be useful if you want to use very new or experimental features, but please use the other group_* 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, groups_url=None, api_host='api.mixpanel.com', retry_limit=4, retry_backoff_factor=0.25, verify_cert=True)¶

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
groups_url (str) – override the default groups API endpoint
api_host (str) – the Mixpanel API domain where all requests should be issued (unless overridden by above URLs).
retry_limit (int) – number of times to retry each retry in case of connection or HTTP 5xx error; 0 to fail after first attempt.
retry_backoff_factor (int) – In case of retries, controls sleep time. e.g., sleep_seconds = backoff_factor * (2 ^ (num_total_retries - 1)).
verify_cert (bool) – whether to verify the server certificate.

New in version 4.6.0: The api_host parameter.

New in version 4.8.0: The verify_cert parameter.

send(endpoint, json_message, api_key=None, api_secret=None)¶

Immediately record an event or a profile update.

Parameters

endpoint ("events" | "people" | "groups" | "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
api_secret (str) – your Mixpanel project’s API secret

Raises

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

New in version 4.8.0: The api_secret parameter.

class mixpanel.BufferedConsumer(max_size=50, events_url=None, people_url=None, import_url=None, request_timeout=None, groups_url=None, api_host='api.mixpanel.com', retry_limit=4, retry_backoff_factor=0.25, verify_cert=True)¶

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.

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
groups_url (str) – override the default groups API endpoint
api_host (str) – the Mixpanel API domain where all requests should be issued (unless overridden by above URLs).
retry_limit (int) – number of times to retry each retry in case of connection or HTTP 5xx error; 0 to fail after first attempt.
retry_backoff_factor (int) – In case of retries, controls sleep time. e.g., sleep_seconds = backoff_factor * (2 ^ (num_total_retries - 1)).
verify_cert (bool) – whether to verify the server certificate.

New in version 4.6.0: The api_host parameter.

New in version 4.8.0: The verify_cert parameter.

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.

send(endpoint, json_message, api_key=None, api_secret=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" | "groups" | "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
api_secret (str) – your Mixpanel project’s API secret

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().