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