mixpanel_api package

Module contents

class mixpanel_api.Mixpanel(api_secret, token=None, dataset_id=None, timeout=120, pool_size=None, read_pool_size=2, max_retries=4, debug=False)

Bases: object

An object for querying, importing, exporting and modifying Mixpanel data via their various APIs

BETA_IMPORT_API = 'https://api-beta.mixpanel.com'

FORMATTED_API = 'https://mixpanel.com/api'

IMPORT_API = 'https://api.mixpanel.com'

LOGGER = <logging.Logger object>

RAW_API = 'https://data.mixpanel.com/api'

VERSION = '2.0'

__init__(api_secret, token=None, dataset_id=None, timeout=120, pool_size=None, read_pool_size=2, max_retries=4, debug=False)

Initializes the Mixpanel object

Parameters:

• api_secret (str) – API Secret for your project
• token (str) – Project Token for your project, required for imports
• dataset_id (str) – The name of the dataset to operate on
• timeout (int) – Time in seconds to wait for HTTP responses
• pool_size (int) – Number of threads to use for sending data to Mixpanel (Default value = cpu_count * 2)
• read_pool_size (int) – Separate number of threads to use just for read operations (i.e. query_engage) (Default value = 2)
• max_retries (int) – Maximum number of times to retry when a 5xx HTTP response is received (Default value = 4)
• debug (bool) – Enable debug logging

_datasets_request(method, dataset_id=None, versions_request=False, version_id=None, state=None)

Internal base method for making calls to the /datasets API

Parameters:

• method (str) – HTTP method verb: ‘GET’, ‘POST’, ‘PUT’, ‘DELETE’, ‘PATCH’
• dataset_id (str) – Name of the dataset to operate on
• versions_request (bool) – Boolean indicating whether or not this request goes to /datasets/versions
• version_id (str) – version_id to operate on
• state (dict) – version state object for use when updating the version

Returns:

Returns the (parsed json) ‘data’ attribute of the response. Type depends on the specific API call. If there is no ‘error’ and ‘data’ is None, returns True. Otherwise returns False.

_dispatch_batches(base_url, endpoint, item_list, prep_args, dataset_id=None, dataset_version=None)

Asynchronously sends batches of items to the /import, /engage, /import-events or /import-people Mixpanel API endpoints

Parameters:

• base_url (str) – The base API url
• endpoint (str) – Can be ‘import’, ‘engage’, ‘/import-events’ or ‘/import-people’
• item_list (list) – List of Mixpanel event data or People updates
• prep_args (list) – List of arguments to be provided to the appropriate _prep method in addition to the profile or event
• dataset_id (str) – Dataset name to import into, required if dataset_version is specified, otherwise optional
• dataset_version (str) – Dataset version to import into, required if dataset_id is specified, otherwise optional

static _dt_from_iso(profile)

Takes a Mixpanel People profile and returns a datetime object for the $last_seen value or datetime.min if $last_seen is not set

Parameters:profile (dict) – A Mixpanel People profile dict Returns:A datetime representing the $last_seen value for the given profile Return type:datetime

static _event_object_from_csv_row(row, header, event_index=None, distinct_id_index=None, time_index=None, time_converter=None)

Converts a row from a csv file into a Mixpanel event dict

Parameters:

• row (list) – A list containing the Mixpanel event data from a csv row
• header (list) – A list containing the csv column headers
• event_index (int) – Index of the event name in row list, if None this method will determine the index (Default value = None)
• distinct_id_index (int) – Index of the distinct_id in row list, if None this method will determine the index (Default value = None)
• time_index (int) – Index of the time property in row list, if None this method will determine the index (Default value = None)
• time_converter ((value) -> int) – A function to convert the value at time_index into a Unix epoch timestamp int in seconds

Returns:

A Mixpanel event object

Return type:

dict

static _export_jql_items(items, output_file, format='json', compress=False)

Based method for exporting jql events or jql people to disk

Parameters:

• items (list | str) – json list or csv data
• output_file (str) – Name of the file to write to
• format (str) – Data format for the output can be ‘json’ or ‘csv’, should match the data type in items
• compress (bool) – Optionally gzip the output file

_get_engage_page(params)

Fetches and returns the response from an /engage request

Parameters:params (dict) – Query parameters for the /engage API Returns:/engage API response object Return type:dict

static _gzip_file(filename)

gzip an existing file

Parameters:filename (str) – Path to a file to be gzipped

_import_data(data, base_url, endpoint, timezone_offset=None, ignore_alias=False, dataset_id=None, dataset_version=None, raw_record_import=False)

Base method to import either event data or People profile data as a list of dicts or from a JSON array file

Parameters:

• data (list | str) – A list of event or People profile dicts or the name of a file containing a JSON array or CSV of events or People profiles
• endpoint (str) – can be ‘import’ or ‘engage’
• timezone_offset (int | float) – UTC offset (number of hours) for the project that exported the data. Used to convert the event timestamps back to UTC prior to import. (Default value = 0)
• ignore_alias (bool) – Option to bypass Mixpanel’s alias lookup table (Default value = False)
• dataset_id (str) – Dataset name to import into, required if dataset_version is specified, otherwise optional
• dataset_version (str) – Dataset version to import into, required if dataset_id is specified, otherwise optional
• raw_record_import (bool) – Set this to True if data is a list of People update operations

static _list_from_argument(arg)

Returns a list given a string with the path to file of Mixpanel data or an existing list

Parameters:arg (list | str) – A string file path or a list Returns:A list of Mixpanel events or profiles Return type:list

static _list_from_items_filename(filename)

Returns a list of Mixpanel events or profiles given the path to a file containing such data

Parameters:filename (str) – Path to a file containing a JSON array of Mixpanel event or People profile data Returns:A list of Mixpanel events or profiles Return type:list

static _people_object_from_csv_row(row, header, distinct_id_index=None)

Converts a row from a csv file into a Mixpanel People profile dict

Parameters:

• row (list) – A list containing the Mixpanel event data from a csv row
• header (list) – A list containing the csv column headers
• distinct_id_index (int) – Index of the distinct_id in row list, if None this method will determine the index (Default value = None)

Returns:

A Mixpanel People profile object

Return type:

dict

static _prep_event_for_import(event, token, timezone_offset)

Takes an event dict and modifies it to meet the Mixpanel /import HTTP spec or dumps it to disk if it is invalid

Parameters:

• event (dict) – A Mixpanel event dict
• token (str) – A Mixpanel project token
• timezone_offset (int | float) – UTC offset (number of hours) of the timezone setting for the project that exported the data. Needed to convert the timestamp back to UTC prior to import.

Returns:

Mixpanel event dict with token added and timestamp adjusted to UTC

Return type:

dict

static _prep_params_for_profile(profile, token, operation, value, ignore_alias, dynamic)

Takes a People profile dict and returns the parameters for an /engage API update

Parameters:

• profile (dict) – A Mixpanel People profile dict
• token (str) – A Mixpanel project token
• operation (str) – A Mixpanel /engage API update operation https://mixpanel.com/help/reference/http#update-operations
• value (dict | list | str | (profile) -> dict | (profile) -> list) – The value to use for the operation or a function that takes a People profile and returns the value to use
• ignore_alias (bool) – Option to bypass Mixpanel’s alias lookup table
• dynamic (bool) – Should be set to True if value param is a function, otherwise false.

Returns:

Parameters for a Mixpanel /engage API update

Return type:

dict

static _properties_from_csv_row(row, header, ignored_columns)

Converts a row from a csv file into a properties dict

Parameters:

• row (list) – A list containing the csv row data
• header (list) – A list containing the column headers (property names)
• ignored_columns (list) – A list of columns (properties) to exclude

_query_jql_items(data_type, from_date=None, to_date=None, event_selectors=None, user_selectors=None, output_properties=None, timezone_offset=0, format='json')

Base method for querying jql for events or People

Parameters:

• data_type – Can be either ‘users’ or ‘people’
• from_date – Date to query events from, can be a datetime object or str of form ‘YYYY-MM-DD’. Only used

when data_type=’events’ :param to_date: Date to query events to, can be a datetime object or str of form ‘YYYY-MM-DD’. Only used when data_type=’events’ :param event_selectors: A single event selector dict or a list of event selector dicts. Only used when data_type=’events :param user_selectors: A selector string or a list of selector dicts. Only used when data_type=’people’ :param output_properties: A list of strings of property names to include in the output :param timezone_offset: UTC offset in hours of export project timezone setting. If set, used to convert event

timestamps from project time to UTC. Only used when data_type=’events’

Parameters:format (str) – Data format for the output can be either ‘json’ or ‘csv’

static _response_handler_callback(response)

Takes a Mixpanel API response and checks the status

Parameters:response (str) – A Mixpanel API JSON response Raises:RuntimeError – Raises RuntimeError if status is not equal to 1

_send_batch(base_url, endpoint, batch, dataset_id=None, dataset_version=None, retries=0)

POST a single batch of data to a Mixpanel API and return the response

Parameters:

• base_url (str) – The base API url
• endpoint (str) – Can be ‘import’, ‘engage’, ‘import-events’ or ‘import-people’
• batch (list) – List of Mixpanel event data or People updates to import.
• dataset_id (str) – Dataset name to import into, required if dataset_version is specified, otherwise optional
• dataset_version (str) – Dataset version to import into, required if dataset_id is specified, otherwise optional
• retries (int) – Max number of times to retry if we get a HTTP 5xx response (Default value = 0)

Returns:

HTTP response from Mixpanel API

Return type:

str

static _unicode_urlencode(params)

URL encodes a dict of Mixpanel parameters

Parameters:params (dict) – A dict containing Mixpanel parameter names and values Returns:A URL encoded string Return type:str

static _write_items_to_csv(items, output_file)

Writes a list of Mixpanel events or profiles to a csv file

Parameters:

• items (list) – A list of Mixpanel events or profiles
• output_file (str) – A string containing the path and filename to write to

create_dataset_version()

Creates a new dataset version for the current dataset_id. Note that dataset_id must already exist!

Returns:Returns a dataset version object. This version of the dataset is writable by default while the ready and readable flags in the version state are false. Return type:dict

deduplicate_people(profiles=None, prop_to_match='$email', merge_props=False, case_sensitive=False, backup=True, backup_file=None)

Determines duplicate profiles based on the value of a specified property. The profile with the latest $last_seen is kept and the others are deleted. Optionally adds any properties from the profiles to be deleted to the remaining profile using $set_once. Backup files are always created.

Parameters:

• profiles (list | str) – Can be a list of profiles or the name of a file containing a JSON array or CSV of profiles. If this is None all profiles with prop_to_match set will be downloaded. (Default value = None)
• prop_to_match (str) – Name of property whose value will be used to determine duplicates (Default value = ‘$email’)
• merge_props (bool) – Option to call $set_once on remaining profile with all props from profiles to be deleted. This ensures that any properties that existed on the duplicates but not on the remaining profile are preserved. (Default value = False)
• case_sensitive (bool) – Option to use case sensitive or case insensitive matching (Default value = False)
• backup (bool) – True to create backup file otherwise False (default)
• backup_file (str) – Optional filename to use for the backup file (Default value = None)

Returns:

Number of profiles deleted

Return type:

int

delete_dataset_version(version_id)

Deletes the version with version_id of the current dataset_id

Parameters:version_id (str) – version_id of the version to be deleted Returns:True for success, False otherwise. Return type:bool

event_counts_to_people(from_date, events)

Sets the per user count of events in events list param as People properties

Parameters:

• from_date (datetime | str) – A datetime or a date string of format YYYY-MM-DD to begin counting from
• events (list[str]) – A list of strings of event names to be counted

Returns:

Number of profiles operated on

Return type:

int

static export_data(data, output_file, append_mode=False, format='json', compress=False)

Writes and optionally compresses Mixpanel data to disk in json or csv format

Parameters:

• data (list) – A list of Mixpanel events or People profiles, if format=’json’, arbitrary json can be exported
• output_file (str) – Name of file to write to
• append_mode (bool) – Set this to True to append data to an existing file using open() mode ‘a+’, uses open() mode ‘w+’ when False (Default value = False)
• format (str) – Output format can be ‘json’ or ‘csv’ (Default value = ‘json’)
• compress (bool) – Option to gzip output (Default value = False)

export_events(output_file, params, format='json', timezone_offset=None, add_gzip_header=False, compress=False, request_per_day=False, raw_stream=False, buffer_size=1024)

Queries the /export API and writes the Mixpanel event data to disk as a JSON or CSV file. Optionally gzip file.

https://mixpanel.com/help/reference/exporting-raw-data#export-api-reference

Parameters:

• output_file (str) – Name of the file to write to
• params (dict) – Parameters to use for the /export API request
• format (str) – Can be either ‘json’ or ‘csv’ (Default value = ‘json’)
• timezone_offset (int | float) – UTC offset in hours of export project timezone setting. If set, used to convert event timestamps from project time to UTC
• add_gzip_header (bool) – Adds ‘Accept-encoding: gzip’ to the request headers (Default value = False)
• compress (bool) – Option to gzip output_file (Default value = False)
• request_per_day (bool) – Option to make one API request (and output file) per day in the exported date range (Default value = False)
• raw_stream (bool) – Option to stream the newline delimited JSON response directly to output_file. If True, format , timezone_offset and compress arguments are ignored (Default value = False)
• buffer_size (int) – Buffer size in bytes to use if raw_stream is True (Default value = 1024)

export_jql_events(output_file, from_date, to_date, event_selectors=None, output_properties=None, timezone_offset=0, format='json', compress=False)

Export events to disk via JQL. Optional whitelist of properties to include in the output.

Parameters:

• output_file (str) – Name of the file to write to
• from_date (datetime | str) – Date to export events from, can be a datetime object or str of form ‘YYYY-MM-DD’
• to_date (datetime | str) – Date to export events to,, can be a datetime object or str of form ‘YYYY-MM-DD’
• event_selectors (dict | list[dict]) – A single event selector dict or a list of event selector dicts
• output_properties (list[str]) – A list of strings of property names to include in the output
• timezone_offset (int | float) – UTC offset in hours of export project timezone setting. If set, used to convert event timestamps from project time to UTC
• format (str) – Data format for the output can be either ‘json’ or ‘csv’
• compress (bool) – Optionally gzip the output

export_jql_people(output_file, user_selectors=None, output_properties=None, format='json', compress=False)

Export People profiles to disk via JQL by providing a single selector string or a list of selector dicts. Optional whitelist of properties to include in the output.

Parameters:

• output_file (str) – Name of the file to write to
• user_selectors (str | list[dict]) – A selector string or a list of selector dicts
• output_properties (list[str]) – A list of strings of property names to include in the output
• format (str) – Data format for the output can be ‘json’ or ‘csv’
• compress (bool) – Optionally gzip the output

export_people(output_file, params=None, timezone_offset=None, format='json', compress=False)

Queries the /engage API and writes the Mixpanel People profile data to disk as a JSON or CSV file. Optionally gzip file.

https://mixpanel.com/help/reference/data-export-api#people-analytics

Parameters:

• output_file (str) – Name of the file to write to
• params (dict) – Parameters to use for the /engage API request (Default value = None)
• timezone_offset (int | float) – UTC offset in hours of project timezone setting, used to calculate as_of_timestamp parameter for queries that use behaviors. Required if query_params contains behaviors (Default value = None)
• format (str) – (Default value = ‘json’)
• compress (bool) – (Default value = False)

formatter = <logging.Formatter object>

import_events(data, timezone_offset, dataset_version=None)

Imports a list of Mixpanel event dicts or a file containing a JSON array of Mixpanel events.

https://mixpanel.com/help/reference/importing-old-events

Parameters:

• data (list | str) – A list of Mixpanel event dicts or the name of a file containing a JSON array or CSV of Mixpanel events
• timezone_offset (int | float) – UTC offset (number of hours) for the project that exported the data. Used to convert the event timestamps back to UTC prior to import.
• dataset_version (str) – Dataset version to import into, required if self.dataset_id is set, otherwise optional

import_people(data, ignore_alias=False, dataset_version=None, raw_record_import=False)

Imports a list of Mixpanel People profile dicts (or raw API update operations) or a file containing a JSON

array or CSV of Mixpanel People profiles (or raw API update operations).

https://mixpanel.com/help/reference/http#people-analytics-updates

Parameters:

• data (list | str) – A list of Mixpanel People profile dicts (or /engage API update operations) or the name of a file containing a JSON array of Mixpanel People profiles (or /engage API update operations).
• ignore_alias (bool) – Option to bypass Mixpanel’s alias lookup table (Default value = False)
• dataset_version (str) – Dataset version to import into, required if self.dataset_id is set, otherwise optional
• raw_record_import – Set this to True if data is a list of API update operations (Default value = False)

jql_operation(jql_script, people_operation, update_value=<function <lambda>>, jql_params=None, ignore_alias=False, backup=True, backup_file=None)

Perform a JQL query to return a JSON array of objects that can then be used to dynamically construct People

updates via the update_value

Parameters:

• jql_script (str) – String containing a JQL script to run. The result should be an array of objects. Those objects should contain at least a $distinct_id key
• people_operation (str) – A Mixpanel People update operation
• update_value – Can be a static value applied to all $distinct_ids or a user defined function or lambda that expects a dict containing at least a $distinct_id (or distinct_id) key, as its only parameter and returns the value to use for the update on that $distinct_id. The default is a lambda that returns the value at the dict’s ‘value’ key.
• jql_params (dict) – Optional dict that will be made available to the script as the params global variable. (Default value = None)
• ignore_alias (bool) – True or False (Default value = False)
• backup (bool) – True to create backup file otherwise False (default)
• backup_file (str) – Optional filename to use for the backup file (Default value = None)

Returns:

Number of profiles operated on

Return type:

int

list_all_dataset_versions()

Returns a list of all dataset version objects for the current dataset_id

Returns:A list of dataset version objects Return type:list

list_dataset_version(version_id)

Returns the dataset version object with the specified version_id for the current dataset_id

Parameters:version_id (str) – version_id of the dataset version object to return Returns:Returns a dataset version object Return type:dict

mark_dataset_version_readable(version_id)

Updates the readable field of the specified version_id’s state to true for the current dataset_id

Parameters:version_id (str) – version_id of the version to be marked readable Returns:True for success, False otherwise. Return type:bool

people_add(value, profiles=None, query_params=None, timezone_offset=None, ignore_alias=False, backup=True, backup_file=None)

Increments numeric properties on the specified profiles using the $add operation and optionally creates a backup file

Parameters:

• value (dict[str, float] | (profile) -> dict[str, float]) – Can be a static value applied to all profiles or a user-defined function (or lambda) that takes a profile as its only parameter and returns the value to use for the operation on the given profile
• profiles (list | str) – Can be a list of profiles or the name of a file containing a JSON array or CSV of profiles. Alternative to query_params. (Default value = None)
• query_params (dict) – Parameters to query /engage API. Alternative to profiles param. (Default value = None)
• timezone_offset (int | float) – UTC offset in hours of project timezone setting, used to calculate as_of_timestamp parameter for queries that use behaviors. Required if query_params contains behaviors (Default value = None)
• ignore_alias (bool) – True or False (Default value = False)
• backup (bool) – True to create backup file otherwise False (default)
• backup_file (str) – Optional filename to use for the backup file (Default value = None)

Returns:

Number of profiles operated on

Return type:

int

people_append(value, profiles=None, query_params=None, timezone_offset=None, ignore_alias=False, backup=True, backup_file=None)

Appends values to list properties on the specified profiles using the $append operation and optionally creates a backup file.

Parameters:

• value (dict | (profile) -> dict) – Can be a static value applied to all profiles or a user-defined function (or lambda) that takes a profile as its only parameter and returns the value to use for the operation on the given profile
• profiles (list | str) – Can be a list of profiles or the name of a file containing a JSON array or CSV of profiles. Alternative to query_params. (Default value = None)
• query_params (dict) – Parameters to query /engage API. Alternative to profiles param. (Default value = None)
• timezone_offset (int | float) – UTC offset in hours of project timezone setting, used to calculate as_of_timestamp parameter for queries that use behaviors. Required if query_params contains behaviors (Default value = None)
• ignore_alias (bool) – True or False (Default value = False)
• backup (bool) – True to create backup file otherwise False (default)
• backup_file (str) – Optional filename to use for the backup file (Default value = None)

Returns:

Number of profiles operated on

Return type:

int

people_change_property_name(old_name, new_name, profiles=None, query_params=None, timezone_offset=None, ignore_alias=False, backup=True, backup_file=None, unset=True)

Copies the value of an existing property into a new property and optionally unsets the existing property. Optionally creates a backup file.

Parameters:

• old_name – The name of an existing property.
• new_name – The new name to replace the old_name with
• profiles (list | str) – Can be a list of profiles or the name of a file containing a JSON array or CSV of profiles. Alternative to query_params. (Default value = None)
• query_params (dict) – Parameters to query /engage API. Alternative to profiles param. If both query_params and profiles are None all profiles with old_name set are targeted. (Default value = None)
• timezone_offset (int | float) – UTC offset in hours of project timezone setting, used to calculate as_of_timestamp parameter for queries that use behaviors. Required if query_params contains behaviors (Default value = None)
• ignore_alias (bool) – True or False (Default value = False)
• backup (bool) – True to create backup file otherwise False (default)
• backup_file (str) – Optional filename to use for the backup file (Default value = None)
• unset (bool) – Option to unset the old_name property (Default value = True)

Returns:

Number of profiles operated on

Return type:

int

people_delete(profiles=None, query_params=None, timezone_offset=None, ignore_alias=True, backup=True, backup_file=None)

Deletes the specified People profiles with the $delete operation and creates a backup file

Parameters:

• profiles (list | str) – Can be a list of profiles or the name of a file containing a JSON array or CSV of profiles. Alternative to query_params. (Default value = None)
• query_params (dict) – Parameters to query /engage API. Alternative to profiles param. (Default value = None)
• timezone_offset (int | float) – UTC offset in hours of project timezone setting, used to calculate as_of_timestamp parameter for queries that use behaviors. Required if query_params contains behaviors (Default value = None)
• ignore_alias (bool) – True or False (Default value = True)
• backup (bool) – True to create backup file otherwise False (default value = True)
• backup_file (str) – Optional filename to use for the backup file (Default value = None)

Returns:

Number of profiles deleted

Return type:

int

people_operation(operation, value, profiles=None, query_params=None, timezone_offset=None, ignore_alias=False, backup=False, backup_file=None)

Base method for performing any of the People analytics update operations

https://mixpanel.com/help/reference/http#update-operations

Parameters:

• operation (str) – A string with name of a Mixpanel People operation, like $set or $delete
• value – Can be a static value applied to all profiles or a user-defined function (or lambda) that takes a profile as its only parameter and returns the value to use for the operation on the given profile
• profiles (list | str) – Can be a list of profiles or the name of a file containing a JSON array or CSV of profiles. Alternative to query_params. (Default value = None)
• query_params (dict) – Parameters to query /engage API. Alternative to profiles param. (Default value = None)
• timezone_offset (int | float) – UTC offset in hours of project timezone setting, used to calculate as_of_timestamp parameter for queries that use behaviors. Required if query_params contains behaviors (Default value = None)
• ignore_alias (bool) – True or False (Default value = False)
• backup (bool) – True to create backup file otherwise False (default)
• backup_file (str) – Optional filename to use for the backup file (Default value = None)

Returns:

Number of profiles operated on

Return type:

int

people_remove(value, profiles=None, query_params=None, timezone_offset=None, ignore_alias=False, backup=True, backup_file=None)

Removes values from list properties on the specified profiles using the $remove operation and optionally creates a backup file

Parameters:

• value (dict | (profile) -> dict) – Can be a static value applied to all profiles or a user-defined function (or lambda) that takes a profile as its only parameter and returns the value to use for the operation on the given profile
• profiles (list | str) – Can be a list of profiles or the name of a file containing a JSON array or CSV of profiles. Alternative to query_params. (Default value = None)
• query_params (dict) – Parameters to query /engage API. Alternative to profiles param. (Default value = None)
• timezone_offset (int | float) – UTC offset in hours of project timezone setting, used to calculate as_of_timestamp parameter for queries that use behaviors. Required if query_params contains behaviors (Default value = None)
• ignore_alias (bool) – True or False (Default value = False)
• backup (bool) – True to create backup file otherwise False (default)
• backup_file (str) – Optional filename to use for the backup file (Default value = None)

Returns:

Number of profiles operated on

Return type:

int

people_revenue_property_from_transactions(profiles=None, query_params=None, timezone_offset=None, ignore_alias=False, backup=True, backup_file=None)

Creates a property named ‘Revenue’ for the specified profiles by summing their $transaction $amounts and optionally creates a backup file

Parameters:

• profiles (list | str) – Can be a list of profiles or the name of a file containing a JSON array or CSV of profiles. Alternative to query_params. (Default value = None)
• query_params (dict) – Parameters to query /engage API. Alternative to profiles param. If both query_params and profiles are None, all profiles with $transactions are targeted. (Default value = None)
• timezone_offset (int | float) – UTC offset in hours of project timezone setting, used to calculate as_of_timestamp parameter for queries that use behaviors. Required if query_params contains behaviors (Default value = None)
• ignore_alias (bool) – True or False (Default value = False)
• backup (bool) – True to create backup file otherwise False (default)
• backup_file (str) – Optional filename to use for the backup file (Default value = None)

Returns:

Number of profiles operated on

Return type:

int

people_set(value, profiles=None, query_params=None, timezone_offset=None, ignore_alias=False, backup=True, backup_file=None)

Sets People properties for the specified profiles using the $set operation and optionally creates a backup file

Parameters:

• value – Can be a static value applied to all profiles or a user-defined function (or lambda) that takes a profile as its only parameter and returns the value to use for the operation on the given profile
• profiles (list | str) – Can be a list of profiles or the name of a file containing a JSON array or CSV of profiles. Alternative to query_params. (Default value = None)
• query_params (dict) – Parameters to query /engage API. Alternative to profiles param. (Default value = None)
• timezone_offset (int | float) – UTC offset in hours of project timezone setting, used to calculate as_of_timestamp parameter for queries that use behaviors. Required if query_params contains behaviors (Default value = None)
• ignore_alias (bool) – True or False (Default value = False)
• backup (bool) – True to create backup file otherwise False (default)
• backup_file (str) – Optional filename to use for the backup file (Default value = None)

Returns:

Number of profiles operated on

Return type:

int

people_set_once(value, profiles=None, query_params=None, timezone_offset=None, ignore_alias=False, backup=False, backup_file=None)

Sets People properties for the specified profiles only if the properties do not yet exist, using the $set_once operation and optionally creates a backup file

Parameters:

• value – Can be a static value applied to all profiles or a user-defined function (or lambda) that takes a profile as its only parameter and returns the value to use for the operation on the given profile
• profiles (list | str) – Can be a list of profiles or the name of a file containing a JSON array or CSV of profiles. Alternative to query_params. (Default value = None)
• query_params (dict) – Parameters to query /engage API. Alternative to profiles param. (Default value = None)
• timezone_offset (int | float) – UTC offset in hours of project timezone setting, used to calculate as_of_timestamp parameter for queries that use behaviors. Required if query_params contains behaviors (Default value = None)
• ignore_alias (bool) – True or False (Default value = False)
• backup (bool) – True to create backup file otherwise False (default)
• backup_file (str) – Optional filename to use for the backup file (Default value = None)

Returns:

Number of profiles operated on

Return type:

int

people_union(value, profiles=None, query_params=None, timezone_offset=None, ignore_alias=False, backup=True, backup_file=None)

Union a list of values with list properties on the specified profiles using the $union operation and optionally create a backup file

Parameters:

• value (dict[str, list] | (profile) -> dict[str, list]) – Can be a static value applied to all profiles or a user-defined function (or lambda) that takes a profile as its only parameter and returns the value to use for the operation on the given profile
• profiles (list | str) – Can be a list of profiles or the name of a file containing a JSON array or CSV of profiles. Alternative to query_params. (Default value = None)
• query_params (dict) – Parameters to query /engage API. Alternative to profiles param. (Default value = None)
• timezone_offset (int | float) – UTC offset in hours of project timezone setting, used to calculate as_of_timestamp parameter for queries that use behaviors. Required if query_params contains behaviors (Default value = None)
• ignore_alias (bool) – True or False (Default value = False)
• backup (bool) – True to create backup file otherwise False (default)
• backup_file (str) – Optional filename to use for the backup file (Default value = None)

Returns:

Number of profiles operated on

Return type:

int

people_unset(value, profiles=None, query_params=None, timezone_offset=None, ignore_alias=False, backup=True, backup_file=None)

Unsets properties from the specified profiles using the $unset operation and optionally creates a backup file

Parameters:

• value (list | (profile) -> list) – Can be a static value applied to all profiles or a user-defined function (or lambda) that takes a profile as its only parameter and returns the value to use for the operation on the given profile
• profiles (list | str) – Can be a list of profiles or the name of a file containing a JSON array or CSV of profiles. Alternative to query_params. (Default value = None)
• query_params (dict) – Parameters to query /engage API. Alternative to profiles param. (Default value = None)
• timezone_offset (int | float) – UTC offset in hours of project timezone setting, used to calculate as_of_timestamp parameter for queries that use behaviors. Required if query_params contains behaviors (Default value = None)
• ignore_alias (bool) – True or False (Default value = False)
• backup (bool) – True to create backup file otherwise False (default)
• backup_file (str) – Optional filename to use for the backup file (Default value = None)

Returns:

Number of profiles operated on

Return type:

int

query_engage(params=None, timezone_offset=None)

Queries the /engage API and returns a list of Mixpanel People profile dicts

https://mixpanel.com/help/reference/data-export-api#people-analytics

Parameters:

• params (dict) – Parameters to use for the /engage API request. Defaults to returning all profiles. (Default value = None)
• timezone_offset (int | float) – UTC offset in hours of project timezone setting, used to calculate as_of_timestamp parameter for queries that use behaviors. Required if query_params contains behaviors (Default value = None)

Raises:

RuntimeError – Raises Runtime error if params include behaviors and timezone_offset is None

Returns:

A list of Mixpanel People profile dicts

Return type:

list

query_export(params, add_gzip_header=False, raw_stream=False)

Queries the /export API and returns a list of Mixpanel event dicts

https://mixpanel.com/help/reference/exporting-raw-data#export-api-reference

Parameters:

• params (dict) – Parameters to use for the /export API request
• add_gzip_header (bool) – Adds ‘Accept-encoding: gzip’ to the request headers (Default value = False)
• raw_stream (bool) – Returns the raw file-like response directly from urlopen instead of creating a list

Returns:

A list of Mixpanel event dicts

Return type:

list

query_jql(script, params=None, format='json')

Query the Mixpanel JQL API

https://mixpanel.com/help/reference/jql/api-reference#api/access

Parameters:

• script (str) – String containing a JQL script to run
• params (dict) – Optional dict that will be made available to the script as the params global variable.
• format (str) – Output format can be either ‘json’ or ‘csv’

Returns:

query output as json or a csv str

query_jql_events(from_date, to_date, event_selectors=None, timezone_offset=0, output_properties=None, format='json')

Query JQL for events. Optional whitelist of properties to include in the output.

Parameters:

• from_date (datetime | str) – Date to export events from, can be a datetime object or str of form ‘YYYY-MM-DD’
• to_date (datetime | str) – Date to export events to,, can be a datetime object or str of form ‘YYYY-MM-DD’
• event_selectors (dict | list[dict]) – A single event selector dict or a list of event selector dicts
• timezone_offset (int | float) – UTC offset in hours of export project timezone setting. If set, used to convert event timestamps from project time to UTC
• output_properties (list[str]) – A list of strings of property names to include in the output
• format (str) – Data format for the output can be either ‘json’ or ‘csv’

query_jql_people(user_selectors=None, output_properties=None, format='json')

Query JQL for profiles by providing a single selector string or a list of selector dicts. Optional whitelist of properties to include in the output.

Parameters:

• user_selectors (str | list[dict]) – A selector string or a list of selector dicts
• output_properties (list[str]) – A list of strings of property names to include in the output
• format (str) – Data format for the output can be ‘json’ or ‘csv’

request(base_url, path_components, params, method='GET', headers=None, raw_stream=False, retries=0)

Base method for sending HTTP requests to the various Mixpanel APIs

Parameters:

• base_url (str) – Ex: https://api.mixpanel.com
• path_components (list) – endpoint path as list of strings
• params (dict) – dictionary containing the Mixpanel parameters for the API request
• method (str) – HTTP method verb: ‘GET’, ‘POST’, ‘PUT’, ‘DELETE’, ‘PATCH’
• headers (dict) – HTTP request headers dict (Default value = None)
• raw_stream (bool) – Return the raw file-like response directly from urlopen, only works when base_url is Mixpanel.RAW_API
• retries (int) – number of times the request has been retried (Default value = 0)

Returns:

JSON data returned from API

Return type:

str

sh = <logging.StreamHandler object>

static sum_transactions(profile)

Returns a dict with a single key, ‘Revenue’ and the sum of all $transaction $amounts for the given profile as the value

Parameters:profile (dict) – A Mixpanel People profile dict Returns:A dict with key ‘Revenue’ and value containing the sum of all $transactions for the give profile Return type:dict

update_dataset_version(version_id, state)

Updates a specific version_id for the current dataset_id. Currently, users can only update the state

of a given dataset version. Only the readable and writable boolean fields can be updated.

Parameters:

• version_id (str) – version_id of the version to be updated
• state (dict) – State object with fields to be updated

Returns:

True for success, False otherwise.

Return type:

bool

wait_until_dataset_version_ready(version_id)

Polls the ready state of the specified version_id for the current dataset_id every 60 seconds until it’s True

Parameters:version_id (str) – version_id of the dataset_version to check if ready Returns:Returns True once the dataset version’s ready field is true. Returns False if the dataset version isn’t found Return type:bool