If you ever need help, please email us at support@mixpanel.com
Back to topics

HTTP Specification (insert data)

Updated Nov. 23, 2011

This document describes how to form HTTP requests to send events to Mixpanel from your backend. In addition, there are several libraries in popular languages available that do the heavy lifting for you.

URI: http://api.mixpanel.com

Endpoint: /track

Logs event based data to our servers, both GET and POST are permitted. We strongly encourage you to use non-blocking solutions such as a queue service like Kestrel. Storage, processing, and analysis are done after the request is received.

Example

http://api.mixpanel.com/track/?data=eyJldmVudCI6ICJnYW1lIiwgInByb3BlcnRpZXMi
OiB7ImlwIjogIjEyMy4xMjMuMTIzLjEyMyIsICJ0b2tlbiI6ICJlM2JiNDEwMDMzMGMzNTcyMjc0
MGZiOGM2ZjVhYmRkYyIsICJ0aW1lIjogMTI0NTYxMzg4NSwgImFjdGlvbiI6ICJwbGF5In19&ip=1

This is a Base64 encoded JSON dictionary/associative array that takes on the structure of:

{   "event": "game", 
    "properties": {
        "ip": "123.123.123.123", 
        "token": "e3bc4100330c35722740fb8c6f5abddc", 
        "time": 1245613885, 
        "action": "play"
    }
}

Note: Also please be aware our flavor of base64 includes the following characters: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=". Additionally, our API only accepts padded Base64 encoded strings.

Response

  • 1 - Data was logged
  • 0 - Error, data was not logged

mpmetrics.jsonp_callback(1/0); // For JSONP requests

Special properties

Mixpanel has some reserved properties that cannot be used, if they are, they will simply be ignored or overwritten.

Properties prefixed with 'mp_' will be ignored during data analysis. You should refrain from using properties like this completely.

Additionally, there are reserved properties that are available for your use but will not be shown to you during analysis:

  • time is the time at which the event occured, it must be a unix timestamp, requests will be rejected that are 48 hours older than codesent time. Format is seconds since 1970, GMT time zone.
  • distinct_id is any string that uniquely can identify a user. You can pass user ids as well.
  • token is the token we provide when you create your project, it's located in your dashboard.
  • ip is a raw string IP Address (e.g. "127.0.0.1") that you pass to our API. This is largely useful if you're making requests from your backend and would like geolocation processing done on your requests otherwise it's safe to use the &ip=1 parameter described in the docs that is outside of the encoded data string.
  • mp_name_tag is the way to set a name for a given user for our streams feature. You can set this to any string value like an email, first and last name, or username.

 

Parameters

Required Name Type Description
required data string

This is a Base64 encoded JSON encoded dictionary/associative array.

The JSON encoded string should be in this format: {"event": "YOUR_EVENT", "properties": {"key": "value", "key": "value"}}

Where "event" is a user defined string. Properties are a simple json object of key-value based pairs whose keys and values can be any string.

Alternatively, we accept a Base64 encoded JSON array of dictionaries/associate arrays. In other words, you can also past a list of the events for batch processing. In this case, the JSON encoded string would look like: [{"event": "e1", "properties": {"key": "value"}}, {"event": "e2", "properties": {"key": "value"}}]
Parameter tricks
optional ip boolean
(0 or 1)

Will automatically utilize the IP address from an incoming request as the substitute for the distinct_id parameter if one is not specified. Setting this to 1 will override any IP Address usage in properties.
optional redirect string

Redirect can take any URL address and log metric data based on the values and parameters specified and then redirect a user to any location desired (such as back to your web application). This is useful in situations where you are more restricted and need to track conversions on things.
optional img boolean
(0 or 1)

This parameter takes either 1 or 0 as its value and will display a 1x1 transparent pixel image if used in conjunction with a <img> tag while logging metric data based on any parameters specified above. This is useful, like redirect, in situations where you are more restricted. For example, you could log when users open up bulletins on MySpace by inserting this 1x1 pixel image and track which user sent the bulletin that was opened as well. This can also be used as a non-blocking substitute for certain situations. Simply append the &img=1 parameter to enable this.
optional callback string

Used for jsonp to callback some function in your javascript with the API's response.
optional test boolean
(0 or 1)

Passing 1 to this parameter will let you send data to a high priority rate limited queue to make testing easier in the event we are back logged with data processing. Data will be logged and analyzed based on the project token.