mixpanel 5.1.0 documentation

# 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'>, local_flags_config: LocalFlagsConfig | None = None, remote_flags_config: RemoteFlagsConfig | None = None)

  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.

  Added in version 4.2.0: The serializer parameter.

  property local_flags: LocalFeatureFlagsProvider

    Get the local flags provider if configured for it

  property remote_flags: RemoteFeatureFlagsProvider

    Get the remote flags provider if configured for it

  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.

    Added 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.

    Added 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.

  Added in version 4.6.0: The api_host parameter.

  Added 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

    Added 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.

  Added in version 4.6.0: The api_host parameter.

  Added 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

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