HTTP spec

The Mixpanel HTTP tracking API allows for event-based tracking and people profile handling by sending data to the appropriate URL endpoint.

Alternatively, Mixpanel directly supports tracking libraries for the following platforms:

These libraries typically support a wide range of convenience features, and should be the starting point for using Mixpanel in your application. The HTTP tracking API and the following document describing it will be most useful to you if you need to send data from an unsupported platform, or if you need low-level details for another reason.

Tracking via HTTP

Mixpanel can receive two types of data from your application: events, and profile updates. Both types of data are represented in your requests by Base64-encoded JSON objects, provided to the API as a data query parameter to an endpoint URL.

Events

Events describe things that happen in your application, usually as the result of user interaction; for example, when a customer reads an article, uploads content, or signs up for your service, you can send an event to record the incident.

Events are tracked at endpoint https://api.mixpanel.com/track/.

//This URL tracks an event with Mixpanel

https://api.mixpanel.com/track/?data=eyJldmVudCI6ICJnYW1lIiwgInByb3BlcnRpZXMiOiB7ImlwIjogIjEyMy4xMjMuMTIzLjEyMyIsICJkaXN0aW5jdF9pZCI6ICIxMzc5MyIsICJ0b2tlbiI6ICJlM2JiNDEwMDMzMGMzNTcyMjc0MGZiOGM2ZjVhYmRkYyIsICJ0aW1lIjogMTI0NTYxMzg4NSwgImFjdGlvbiI6ICJwbGF5In19

If the event you are trying to send to Mixpanel is more than 5 days old, the track endpoint above will not accept your request. Instead, you will need to hit the import endpoint at http://api.mixpanel.com/import/ to process your request. Full details on using the import endpoint can be found here.

Profile Updates

People analytics updates describe a fact you've learned about one of your customers. For example, when a customer enters their first name or their birthday into your sign-in form, or signs up for a new level of service, you may send a profile update to record what you've learned.

Profile updates are recorded at endpoint https://api.mixpanel.com/engage/

//This URL sends a profile update to Mixpanel

https://api.mixpanel.com/engage/?data=ew0KICAgICIkdG9rZW4iOiAiMzZhZGE1YjEwZGEzOWExMzQ3NTU5MzIxYmFmMTMwNjMiLA0KICAgICIkZGlzdGluY3RfaWQiOiAiMTM3OTMiLA0KICAgICIkc2V0Ijogew0KICAgICAgICAiJGZpcnN0X25hbWUiOiAiRGF2aWQiLA0KICAgICAgICAiJGxhc3RfbmFtZSI6ICJKb25lcyIsDQogICAgICAgICIkZW1haWwiOiAiYWxhZGRpbi5zYW5lQGV4YW1wbGUuY29tIiwNCiAgICAgICAgIiRjcmVhdGVkIjogIjIwMTMtMDQtMDFUMTM6MjA6MDAiDQogICAgfQ0KfQ==

Base64 for Mixpanel

To Base64 encode data for the Mixpanel API, you should use the following characters:

ABCDEFGHIJKLMNOPQRSTUVWXYZ
abcdefghijklmnopqrstuvwxyz
0123456789+/=

Mixpanel will only accept padded Base64 requests.

Tracking Events

Each event you record is represented as a JSON object in a request to https://api.mixpanel.com/track/. The request will return an HTTP response with body "1" if the track call is successful, and a "0" otherwise. Event tracking objects should have the following attributes:

Argument
Type
Description

event

string
required

A name for the event. For example, "Signed Up", or "Uploaded Photo".

properties

object
required

A collection of properties associated with this event. You can use these properties to filter or segment events in Mixpanel. In addition, some properties are treated specially by Mixpanel.

// Sends an event "Signed Up", associated with user 13793,
// with a property "Referred By"
{
    "event": "Signed Up",
    "properties": {
        // "distinct_id" and "token" are
        // special properties, described below.
        "distinct_id": "13793",
        "token": "e3bc4100330c35722740fb8c6f5abddc",
        "Referred By": "Friend"
    }
}

The JSON string above can be base64 encoded as:

ew0KICAgICJldmVudCI6ICJTaWduZWQgVXAiLA0KICAgICJwcm9wZXJ0aWVzIjogew0KICAgICAgICAiZGlzdGluY3RfaWQiOiAiMTM3OTMiLA0KICAgICAgICAidG9rZW4iOiAiZTNiYzQxMDAzMzBjMzU3MjI3NDBmYjhjNmY1YWJkZGMiLA0KICAgICAgICAiUmVmZXJyZWQgQnkiOiAiRnJpZW5kIg0KICAgIH0NCn0=

Using the base64 encoded value as the data parameter for the Mixpanel event endpoint will result in the following url:

https://api.mixpanel.com/track/?data=ew0KICAgICJldmVudCI6ICJTaWduZWQgVXAiLA0KICAgICJwcm9wZXJ0aWVzIjogew0KICAgICAgICAiZGlzdGluY3RfaWQiOiAiMTM3OTMiLA0KICAgICAgICAidG9rZW4iOiAiZTNiYzQxMDAzMzBjMzU3MjI3NDBmYjhjNmY1YWJkZGMiLA0KICAgICAgICAiUmVmZXJyZWQgQnkiOiAiRnJpZW5kIg0KICAgIH0NCn0=

Special Properties in Events

You can use any UTF-8 string that doesn't begin with "mp_" to name your properties, but some property names have special significance to Mixpanel. All of the special properties except for token are optional, but most events should include a distinct_id. Special properties also enable event deduplication.

Event Deduplication

The combination of $insert_id and time can be used to deduplicate events. Any payload without $insert_id and time will not be deduplicated. Mixpanel generates the $insert_id at the API for payloads that do not contain $insert_id.

Event deduplication can take up to one day to occur. There is no deduplication time window. This means that Mixpanel will deduplicate events even if they arrive multiple weeks or months apart.

The deduplication process currently works with our core reports and with raw data exports.

Events deduplicate if they have the same $insert_id and are ingested during the same 24-hour period. For example, if “Event 1” and “Event 2” have an identical $insert_id and have timestamps that occur during the same 24-hour period, then Mixpanel drops “Event 2”.

Special properties include:

Parameters
Type
Description

token

string
required

The Mixpanel token associated with your project. You can find your Mixpanel token in the project settings dialog in the Mixpanel app. Events without a valid token will be ignored.

distinct_id

string
optional

The value of distinct_id will be treated as a string, and used to uniquely identify a user associated with your event. If you provide a distinct_id property with your events, you can track a given user through funnels and distinguish unique users for retention analyses. You should always send the same distinct_id when an event is triggered by the same user.

time

string
optional

The time an event occurred. If present, the value should be a unix timestamp (seconds since midnight, January 1st, 1970 - UTC). If this property is not included in your request, Mixpanel will use the time the event arrives at the server.

ip

string
optional

An IP address string (e.g. "127.0.0.1") associated with the event. This is used for adding geolocation data to events, and should only be required if you are making requests from your backend. If ip is absent (and ip=1 is not provided as a URL parameter), Mixpanel will ignore the IP address of the request.

$insert_id

string
optional

A random 16 character string of alphanumeric characters that is unique to an event. $insert_id can contain less than 16 characters, but any string longer than 16 characters will be truncated. Mixpanel replaces $insert_id if the value passed contains non-alphanumeric characters.

// Tracks an event, recording the fact that
// user "13793", completed level 9
// on January 15th, 2013 on a machine with ip
// 203.0.113.9
{
    "event": "Level Complete",
    "properties": {
        "Level Number": 9,
        "distinct_id": "13793",
        "token": "e3bc4100330c35722740fb8c6f5abddc",
      	"$insert_id": "p09unabdez2236d7",
        "time": 1358208000,
        "ip": "203.0.113.9"
    }
}

Event Request Parameters

In addition to the data parameter, https://api.mixpanel.com/track supports a number of optional parameters. For the most part, these optional parameters are useful only in special situations.

Parameters
Type
Description

data

object
required

A Base 64 encoded JSON event object, with a name and properties.

ip

1 or 0
optional

If present and equal to 1, Mixpanel will use the ip address of the incoming request as a distinct_id if none is provided.

redirect

url
optional

If present, Mixpanel will serve a redirect to the given url as a response to the request. This is useful when tracking clicks in an email or text message.

img

1 or 0
optional

If present and equal to 1, Mixpanel will serve a 1x1 transparent pixel image as a response to the request. This is useful for tracking page loads and email opens.

callback

function name
optional

If present, Mixpanel will serve a response of type text/javascript, containing a call to a function with the given name. This is useful for reacting to Mixpanel track events in JavaScript.

verbose

1 or 0
optional

If present and equal to 1, Mixpanel will respond with a JSON Object describing the success or failure of the tracking call. The returned object will have two keys: "status", with the value 1 on success and 0 on failure, and "error", with a string-valued error message if the request wasn't successful. verbose=1 is useful for debugging your Mixpanel implementation.

This tracking call will be redirected to http://www.example.com when it responds:

https://api.mixpanel.com/track/?data=eyJldmVudCI6ICJnYW1lIiwgInByb3BlcnRpZXMiOiB7ImlwIjogIjEyMy4xMjMuMTIzLjEyMyIsICJkaXN0aW5jdF9pZCI6ICIxMzc5MyIsICJ0b2tlbiI6ICJlM2JiNDEwMDMzMGMzNTcyMjc0MGZiOGM2ZjVhYmRkYyIsICJ0aW1lIjogMTI0NTYxMzg4NSwgImFjdGlvbiI6ICJwbGF5In19==&redirect=http%3A%2F%2Fwww.example.com

This tracking call will respond with a 1x1 transparent image:

https://api.mixpanel.com/track/?data=eyJldmVudCI6ICJnYW1lIiwgInByb3BlcnRpZXMiOiB7ImlwIjogIjEyMy4xMjMuMTIzLjEyMyIsICJkaXN0aW5jdF9pZCI6IDEzNzkzLCAidG9rZW4iOiAiZTNiYjQxMDAzMzBjMzU3MjI3NDBmYjhjNmY1YWJkZGMiLCAidGltZSI6IDEyNDU2MTM4ODUsICJhY3Rpb24iOiAicGxheSJ9fQ==&img=1

This tracking call will return a text/javascript response, calling the function "wasTracked"

https://api.mixpanel.com/track/?data=eyJldmVudCI6ICJnYW1lIiwgInByb3BlcnRpZXMiOiB7ImlwIjogIjEyMy4xMjMuMTIzLjEyMyIsICJkaXN0aW5jdF9pZCI6IDEzNzkzLCAidG9rZW4iOiAiZTNiYjQxMDAzMzBjMzU3MjI3NDBmYjhjNmY1YWJkZGMiLCAidGltZSI6IDEyNDU2MTM4ODUsICJhY3Rpb24iOiAicGxheSJ9fQ==&callback=wasTracke

Storing User Profiles

Each profile update you send is represented as a JSON object in a request to https://api.mixpanel.com/engage/. The request will return an HTTP response with body "1" if the profile update is successful, and a "0" otherwise. All profile update objects should have the following attributes:

Parameters
Type
Description

$token

string
required

The Mixpanel token associated with your project. You can find your Mixpanel token in the project settings dialog in the Mixpanel app.

$distinct_id

string
required

This is a string that identifies the profile you would like to update. Updates with the same $distinct_id refer to the same profile. If this $distinct_id matches a distinct_id you use in your events, those events will show up in the activity feed associated with the profile you've updated.

$ip

string
optional

The IP address associated with a given profile. If $ip isn't provided (and ip=0 isn't provided as a URL parameter), Mixpanel will use the IP address of the request. Mixpanel uses an IP address to guess at the geographic location of users. If $ip is set to "0", Mixpanel will ignore IP information.

$time


optional

Seconds since midnight, January 1st 1970, UTC. Updates are applied in $time order, so setting this value can lead to unexpected results unless care is taken. If $time is not included in a request, Mixpanel will use the time the update arrives at the Mixpanel server.

$ignore_time

true or false
optional

If the $ignore_time property is present and true in your update request, Mixpanel will not automatically update the "Last Seen" property of the profile. Otherwise, Mixpanel will add a "Last Seen" property associated with the current time for all $set, $append, and $add operations.

$ignore_alias

true or false
optional

If the $ignore_alias property is present and true in your update request, Mixpanel will apply the update directly to the profile with the distinct_id included in the request, rather than allowing this distinct_id to be recognized as an alias during ingestion.

In addition to the attributes common to all updates, every update should also have a key and value associated with a particular update operation. Every call to the profile update API should have a single associated operation - you can't do two operations at once. Each operation has its own key name and format for appropriate values. Typical profile update objects look like this:

{
    "$token": "36ada5b10da39a1347559321baf13063",
    "$distinct_id": "13793",
    "$ip": "123.123.123.123",
    OPERATION_NAME: OPERATION_VALUE
}

Where OPERATION_NAME and OPERATION_VALUE are specific to the operation you are performing. For example, a "$set" operation request might look like this:

{
    "$token": "36ada5b10da39a1347559321baf13063",
    "$distinct_id": "13793",
    "$ip": "123.123.123.123",
    "$set": {
        "Address": "1313 Mockingbird Lane"
    }
}

Update Operations

Mixpanel People analytics supports the following operations on profiles:

$set

Operation
Type
Description

$set

object

Takes a JSON object containing names and values of profile properties. If the profile does not exist, it creates it with these properties. If it does exist, it sets the properties to these values, overwriting existing values.

// sets the "Address" and "Birthday"
// properties of user 13793
{
    "$token": "36ada5b10da39a1347559321baf13063",
    "$distinct_id": "13793",
    "$ip": "123.123.123.123",
    "$set": {
        "Address": "1313 Mockingbird Lane",
        "Birthday": "1948-01-01"
    }
}

$set_once

Operation
Type
Description

$set_once

object

Works just like "$set", except it will not overwrite existing property values. This is useful for properties like "First login date".

// This sets the "First login date" property of user 13793
// if and only if it has never been set before
{
    "$token": "36ada5b10da39a1347559321baf13063",
    "$distinct_id": "13793",
    "$set_once": {
        "First login date": "2013-04-01T13:20:00"
    }
}

$add

Operation
Type
Description

$add

object

Takes a JSON object containing keys and numerical values. $add will increment the value of a people property. When processed, the property values are added to the existing values of the properties on the profile. If the property is not present on the profile, the value will be added to 0. It is possible to decrement by calling "$add" with negative values. This is useful for maintaining the values of properties like "Number of Logins" or "Files Uploaded".

// This adds 12 to a running total of
// Coins Gathered for user 13793
{
    "$token": "36ada5b10da39a1347559321baf13063",
    "$distinct_id": "13793",
    "$add": { "Coins Gathered": 12 }
}

$append

Operation
Type
Description

$append

object

Takes a JSON object containing keys and values, and appends each to a list associated with the corresponding property name. $appending to a property that doesn't exist will result in assigning a list with one element to that property.

// This adds "Bubble Lead" to
// the list "Power Ups" for user 13793
{
    "$token": "36ada5b10da39a1347559321baf13063",
    "$distinct_id": "13793",
    "$append": { "Power Ups": "Bubble Lead" }
}

$union

Operation
Type
Description

$union

object

Takes a JSON object containing keys and list values. The list values in the request are merged with the existing list on the user profile, ignoring duplicate list values.

// This combines ["socks", "shirts"] with the existing values for the "Items purchased"
// list for user 13793, also ensuring that the list values will only appear once in
// the merged list.
{
    "$token": "36ada5b10da39a1347559321baf13063",
    "$distinct_id": "13793",
    "$union": { "Items purchased": ["socks", "shirts"] }
}

$remove

Operation
Type
Description

$remove

object

Takes a JSON object containing keys and values. The value in the request is removed from the existing list on the user profile. If it does not exist, no updates are made.

// This removes "socks" from the "Items purchased" list for user 13793.
{
    "$token": "36ada5b10da39a1347559321baf13063",
    "$distinct_id": "13793",
    "$remove": { "Items purchased": "socks" }
}

$unset

Operation
Type
Description

$unset

list

Takes a JSON list of string property names, and permanently removes the properties and their values from a profile.

// This removes the property "Days Overdue" from user 13793
{
    "$token": "36ada5b10da39a1347559321baf13063",
    "$distinct_id": "13793",
    "$unset": [ "Days Overdue" ]
}

$delete

Operation
Type
Description

$delete

string

Permanently delete the profile from Mixpanel, along with all of its properties. The value is ignored - the profile is determined by the $distinct_id from the request itself.

// This removes the user 13793 from Mixpanel
{
    "$token": "36ada5b10da39a1347559321baf13063",
    "$distinct_id": "13793",
    "$delete": ""
}

Special Properties in Profile Updates

Mixpanel interprets some properties in special ways. If you provide values for these properties, you can enable certain features in Mixpanel reports and messages.

Mixpanel special properties all have names that begin with a dollar sign ("$") - you shouldn't create custom properties that begin with a dollar sign in your profiles, because Mixpanel may add new special properties in the future. A list of selected special properties is below.

Property
Description

$first_name

Should be set to the first and last name of the user represented by the profile. If these are set, the full name of the user will be displayed in Mixpanel reports.

$last_name

Can be set to the user's full name as an alternative to having two separate first and last name properties.

$created

The time when the user created their account. This should be expressed as a Mixpanel date string.

$email

The user's email address as a string, e.g. "joe.doe@example.com". Mixpanel will use the "$email" property when sending email messages to your users, and for displaying the user's gravatar image in reports.

$phone

The user's phone number as a string, e.g. "4805551212". Mixpanel will use the "$phone" property when sending SMS messages to your users.

// You can set $first_name, $last_name, $created, and $email
// special properties just like any other.
{
    "$token": "36ada5b10da39a1347559321baf13063",
    "$distinct_id": "13793",
    "$set": {
        "$first_name": "Joe",
        "$last_name": "Doe",
        "$email": "joe.doe@example.com",
        "$created": "2013-04-01T13:20:00",
        "$phone": "4805551212"
    }
}

Update Request Parameters

In addition to the data parameter, https://api.mixpanel.com/engage/ supports a number of optional parameters. For the most part, these optional parameters are useful only in special situations.

Parameter
Type
Description

data

object
required

A Base 64 encoded JSON update object, with a $token, $distinct_id, and an operation.

redirect

url
optional

If present, Mixpanel will serve a redirect to the given url as a response to the request. This is useful when tracking clicks in an email or text message.

callback

function name
optional

If present, Mixpanel will serve a response of type text/javascript, containing a call to a function with the given name. This is useful for reacting to Mixpanel track events in JavaScript.

Verbose

1 or 0
optional

If present and equal to 1, Mixpanel will respond with a JSON object describing the success or failure of the tracking call. The returned object will have two keys: "status", with the value 1 on success and 0 on failure, and "error", with a string-valued error message if the request wasn't successful. verbose=1 is useful for debugging your Mixpanel implementation.

Base64 Update Examples

A url for a standard update tracking call.

https://api.mixpanel.com/engage/?data=ew0KICAgICIkdG9rZW4iOiAiMzZhZGE1YjEwZGEzOWExMzQ3NTU5MzIxYmFmMTMwNjMiLA0KICAgICIkZGlzdGluY3RfaWQiOiAiMTM3OTMiLA0KICAgICIkc2V0Ijogew0KICAgICAgICAiJGZpcnN0X25hbWUiOiAiRGF2aWQiLA0KICAgICAgICAiJGxhc3RfbmFtZSI6ICJKb25lcyIsDQogICAgICAgICIkZW1haWwiOiAiYWxhZGRpbi5zYW5lQGV4YW1wbGUuY29tIiwNCiAgICAgICAgIiRjcmVhdGVkIjogIjIwMTMtMDQtMDFUMTM6MjA6MDAiDQogICAgfQ0KfQ==

Mixpanel will respond to this tracking call by redirecting to http://www.example.com.

https://api.mixpanel.com/engage/?data=ew0KICAgICIkdG9rZW4iOiAiMzZhZGE1YjEwZGEzOWExMzQ3NTU5MzIxYmFmMTMwNjMiLA0KICAgICIkZGlzdGluY3RfaWQiOiAiMTM3OTMiLA0KICAgICIkc2V0Ijogew0KICAgICAgICAiJGZpcnN0X25hbWUiOiAiRGF2aWQiLA0KICAgICAgICAiJGxhc3RfbmFtZSI6ICJKb25lcyIsDQogICAgICAgICIkZW1haWwiOiAiYWxhZGRpbi5zYW5lQGV4YW1wbGUuY29tIiwNCiAgICAgICAgIiRjcmVhdGVkIjogIjIwMTMtMDQtMDFUMTM6MjA6MDAiDQogICAgfQ0KfQ==&redirect=http%3A%2F%2Fwww.example.com

Mixpanel will respond to this tracking call by serving a text/javascript response, calling function 'wasTracked'.

https://api.mixpanel.com/engage/?data=ew0KICAgICIkdG9rZW4iOiAiMzZhZGE1YjEwZGEzOWExMzQ3NTU5MzIxYmFmMTMwNjMiLA0KICAgICIkZGlzdGluY3RfaWQiOiAiMTM3OTMiLA0KICAgICIkc2V0Ijogew0KICAgICAgICAiJGZpcnN0X25hbWUiOiAiRGF2aWQiLA0KICAgICAgICAiJGxhc3RfbmFtZSI6ICJKb25lcyIsDQogICAgICAgICIkZW1haWwiOiAiYWxhZGRpbi5zYW5lQGV4YW1wbGUuY29tIiwNCiAgICAgICAgIiRjcmVhdGVkIjogIjIwMTMtMDQtMDFUMTM6MjA6MDAiDQogICAgfQ0KfQ==&callback=wasTracked

Group Analytics

Reach out to your Customer Success Manager or the Mixpanel Sales Team to enable Group Analytics in your reports.

Mixpanel Group Analytics allows behavioral data analysis by selected groups, as opposed to individual users.

Grouping by identifiers other than the distinct_id will allow analysis at a company or group level when using Mixpanel analytics. Read this article to learn more about Group Analytics.

A group is identified by the group_key and group_id.

  • group_key is the property that connects event data for Group Analytics.
  • group_id is the identifier for a specific group.

If the property “company” is chosen for Group Analytics, “company” is the group_key, and “Mixpanel”, “Company A”, and “13254” are all potential group_id values.

A user can belong to multiple groups. All updates to a group operate on the group_key and group_id.

Creating a Group Key

You must reach out to your CSM to determine what event property you will use for the group_key in Group Analytics. Please note that merged properties are not supported, so if you merge a "corporation" property into the "company" group_key, you would still need to use the original "company" property as the group_key in your implementation.

Sending Group Identifiers With Events

To send group identifiers with events, send the group_key as a property key and the group_id as the property value. The data type of the group_key property is a list, therefore you can add multiple values for a single user.

Mixpanel can group events by the group_id, similar to how it events are grouped with the distinct_id. A group_id, however, is a group level identifier and not a user level identifier like the distinct_id.

Note that sending in a group_key and group_id as event properties does not add users to the group profile or assign group membership to the user's profile. Only events with your chosen group_key property set will be available for behavioral analysis at the group level.

Adding group identifiers to users is done by sending the group_key and group_id to the /track endpoint. The group identifiers are treated as event properties, and you can therefor add multiple group_key and group_id values.

//Sends an event with a group_key of "company" and a 
//group_id of "Mixpanel"
{
    "event": "Level Complete",
    "properties": {
        "Level Number": 9,
        "distinct_id": "13793",
        "token": "e3bc4100330c35722740fb8c6f5abddc",
      	"$insert_id": "p09unabdez2236d7",
        "time": 1358208000,
        "ip": "203.0.113.9",
        "company": ["Mixpanel"]
    }
}

Adding Group Identifiers to Individual Users

You should also connect group information to an individual’s people profile by sending the update to the /engage endpoint.

To connect group information to a people profile, include the group_key and group_id by sending the property as part of the $set update operation.

//Updates the People Profile with a group_key equal to "company" and a 
//group_id equal to "Mixpanel"
{
    "$token": "36ada5b10da39a1347559321baf13063",
    "$distinct_id": "13793",
    "$ip": "123.123.123.123",
    "$set": {
		"Address": "1313 Mockingbird Lane",
		"Birthday": "1948-01-01",
		"company": ["Mixpanel"]
    }
}

Adding Properties to a Group Profile

Each profile update you send is represented as a JSON object in a request to https://api.mixpanel.com/groups/. Note that this is different from updating events with the group_key and group_id event properties that are sent to the /track endpoint, or people profile updates sent to the /engage endpoint.

Group Profile updates will update the profile available in Mixpanel's Explore report.

The Group Analytics API works similarly to the engage endpoint but has one key difference: $group_key and $group_id must be set, instead of $distinct_id.

set

$set updates or adds a property to a group.

// Example $set: sets the “Address” property for the Mixpanel company profile
{
    "$token": "36ada5b10da39a1347559321baf13063",
    "$group_key": "Company",
    "$group_id": "Mixpanel",
    "$ip": "123.123.123.123",
    "$set": {
        "Address": "1313 Mockingbird Lane"
    }
}

set once

$set_once adds a property value to a group only if it has not been set before.

// Example $set_once: sets the “Address” property for the Mixpanel company
// profile only if it has not been set before
{
    "$token": "36ada5b10da39a1347559321baf13063",
    "$group_key": "Company",
    "$group_id": "Mixpanel",
    "$ip": "123.123.123.123",
    "$set_once": {
        "Address": "1313 Mockingbird Lane"
    }
}

unset

$unset unsets a specific property in the group.

// Example $unset: unsets the "Items purchased" property for Company Mixpanel.
{
    "$token": "36ada5b10da39a1347559321baf13063",
    "$group_key": "Company",
    "$group_id": "Mixpanel",
    "$unset": [ "Items purchased" ]
}

remove

$remove removes a specific value in a list property.

// Example $remove: This removes "socks" from the "Items purchased" list
// property for Company Mixpanel. If “Items purchased” is not a list
// or “socks” does not appear in the list, this operation has no
// effect.
{
    "$token": "36ada5b10da39a1347559321baf13063",
    "$group_key": "Company",
    "$group_id": "Mixpanel",
    "$remove": { "Items purchased": "socks" }
}

union

$union adds the specified values to a list property and ensures that those values only appear once.

// Example $union: This combines ["socks", "shirts"] with the existing values
// for the "Items purchased" list for Company Mixpanel, also ensuring
// that the list values will only appear once in the merged list.
{
    "$token": "36ada5b10da39a1347559321baf13063",
    "$group_key": "Company",
    "$group_id": "Mixpanel",
    "$union": { "Items purchased": ["socks", "shirts"] }
}

Dates in Mixpanel Updates

Properties in updates can be any of the data types valid in JSON: strings, numbers, boolean, null, arrays or objects. In addition, Mixpanel will interpret strings of a particular format as dates. This format is:

YYYY-MM-DDThh:mm:ss

Where:

  • YYYY = four-digit year
  • MM = two-digit month (01=January, etc.)
  • DD = two-digit day of month (01 through 31)
  • T = a literal 'T' character
  • hh = two digits of hour (00 through 23)
  • mm = two digits of minute (00 through 59)
  • ss = two digits of second (00 through 59)

January 15th, 1976, at 9:45 PM can be represented as

1976-01-15T21:45:00

So, to set a "Time Joined" property on user "13793", you can create the following $set object:

{
    "$token": "36ada5b10da39a1347559321baf13063",
    "$distinct_id": "13793",
    "$set": { "Time Joined": "2013-04-01T09:02:00" }
}

NOTE

All date properties should use the UTC timezone. This will be converted to your project's timezone when viewing your reports.

Creating a Distinct_Id Alias

Mixpanel supports adding an alias to a distinct id. An alias is a new value that will be interpreted by Mixpanel as an existing value. That means that you can send messages to Mixpanel using the new value, and Mixpanel will continue to use the old value for calculating funnels and retention reports, or applying updates to people profiles.

Aliases are created by sending a special event, "$create_alias", to the https://api.mixpanel.com/track/ endpoint. The "$create_alias" event must be sent with a property "distinct_id" containing the original id,and a property "alias" containing the new id you would like to map to the old one.

// Creates an alias for "ORIGINAL_ID" with value "NEW_ID".
// New events and updates sent with distinct_id "NEW_ID"
// will be mapped to "ORIGINAL_ID" when they are stored
// in Mixpanel
{
    "event": "$create_alias",
    "properties": {
        "distinct_id": "ORIGINAL_ID",
        "alias": "NEW_ID",
        "token": "e3bc4100330c35722740fb8c6f5abddc"
    }
}

Tracking Revenue

Mixpanel tracks revenue in a profile property named $transactions. $transactions is a list, containing specially formatted JSON objects, one for each purchase or transaction associated with the particular profile.

The easiest way to track revenue is with an $append profile update, sent to https://api.mixpanel.com/engage/. When you record revenue from a user, $append an object with the following attributes:

Attribute
Type
Description

$time

date
required

A string representing the time of transaction, formatted in the profile update date format

$amount

number
required

A number that represents the amount of the transaction.

In addition to the required attributes, you can also include other attributes, like a SKU, product name, or any information that might be useful to associate with an individual transaction. However, properties other than the date and amount are not visible in reports at this time.

To record that the user with distinct id "13793" made a purchase for $25.34 at 9AM on January 3rd, 2013, you might send the following update:

{
    "$append": {
        "$transactions": {
            "$time": "2013-01-03T09:00:00",
            "$amount": 25.34
        }
    },
    "$token": "36ada5b10da39a1347559321baf13063",
    "$distinct_id": "13793"
}

Batch Requests

Both the events endpoint at http://api.mixpanel.com/track/and the profile update endpoint at http://api.mixpanel.com/engage/ accept batched updates. To send a batch of messages to an endpoint, you should use a POST instead of a GET request. Instead of sending a single JSON object as the data query parameter, send a JSON list of objects, base64 encoded, as the data parameter of an application/x-www-form-urlencoded POST request body.

// Here's a list of events
[
    {
        "event": "Signed Up",
        "properties": {
            "distinct_id": "13793",
            "token": "e3bc4100330c35722740fb8c6f5abddc",
            "Referred By": "Friend",
            "time": 1371002000
        }
    },
    {
         "event": "Uploaded Photo",
          "properties": {
              "distinct_id": "13793",
              "token": "e3bc4100330c35722740fb8c6f5abddc",
              "Topic": "Vacation",
              "time": 1371002104
          }
    }
]

Base64 encoded, the list becomes:

Ww0KICAgIHsNCiAgICAgICAgImV2ZW50IjogIlNpZ25lZCBVcCIsDQogICAgICAgICJwcm9wZXJ0aWVzIjogew0KICAgICAgICAgICAgImRpc3RpbmN0X2lkIjogIjEzNzkzIiwNCiAgICAgICAgICAgICJ0b2tlbiI6ICJlM2JjNDEwMDMzMGMzNTcyMjc0MGZiOGM2ZjVhYmRkYyIsDQogICAgICAgICAgICAiUmVmZXJyZWQgQnkiOiAiRnJpZW5kIiwNCiAgICAgICAgICAgICJ0aW1lIjogMTM3MTAwMjAwMA0KICAgICAgICB9DQogICAgfSwNCiAgICB7DQogICAgICAgICAiZXZlbnQiOiAiVXBsb2FkZWQgUGhvdG8iLA0KICAgICAgICAgICJwcm9wZXJ0aWVzIjogew0KICAgICAgICAgICAgICAiZGlzdGluY3RfaWQiOiAiMTM3OTMiLA0KICAgICAgICAgICAgICAidG9rZW4iOiAiZTNiYzQxMDAzMzBjMzU3MjI3NDBmYjhjNmY1YWJkZGMiLA0KICAgICAgICAgICAgICAiVG9waWMiOiAiVmFjYXRpb24iLA0KICAgICAgICAgICAgICAidGltZSI6IDEzNzEwMDIxMDQNCiAgICAgICAgICB9DQogICAgfQ0KXQ==

So the body of a POST request to send the events as a batch is:

data=Ww0KICAgIHsNCiAgICAgICAgImV2ZW50IjogIlNpZ25lZCBVcCIsDQogICAgICAgICJwcm9wZXJ0aWVzIjogew0KICAgICAgICAgICAgImRpc3RpbmN0X2lkIjogIjEzNzkzIiwNCiAgICAgICAgICAgICJ0b2tlbiI6ICJlM2JjNDEwMDMzMGMzNTcyMjc0MGZiOGM2ZjVhYmRkYyIsDQogICAgICAgICAgICAiUmVmZXJyZWQgQnkiOiAiRnJpZW5kIiwNCiAgICAgICAgICAgICJ0aW1lIjogMTM3MTAwMjAwMA0KICAgICAgICB9DQogICAgfSwNCiAgICB7DQogICAgICAgICAiZXZlbnQiOiAiVXBsb2FkZWQgUGhvdG8iLA0KICAgICAgICAgICJwcm9wZXJ0aWVzIjogew0KICAgICAgICAgICAgICAiZGlzdGluY3RfaWQiOiAiMTM3OTMiLA0KICAgICAgICAgICAgICAidG9rZW4iOiAiZTNiYzQxMDAzMzBjMzU3MjI3NDBmYjhjNmY1YWJkZGMiLA0KICAgICAgICAgICAgICAiVG9waWMiOiAiVmFjYXRpb24iLA0KICAgICAgICAgICAgICAidGltZSI6IDEzNzEwMDIxMDQNCiAgICAgICAgICB9DQogICAgfQ0KXQ==

Both endpoints will accept up to 50 messages in a single batch. Usually, batch requests will have a "time" property associated with events, or a "$time" attribute associated with profile updates.

When sending a batch request to Mixpanel, we will invalidate the entire request if one of the objects within the batch is invalid. If you receive an error when attempting to send a batch, please attempt the requests one at a time to isolate the cause of the error.

HTTP spec


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.