Data Export API

Mixpanel lets you pull your data out at any time - which means you can add key graphs to your own internal dashboards with ease.

Client libraries

These are official libraries that can be used to easily consume data through the Mixpanel API.

Python

Download the Python client library

PHP

Download the PHP client library

Ruby

Option 1: Visit the Ruby repository

Option 2: mixpanel-api (Customer contributed)

JavaScript

We do not have a JavaScript client library, but we have implemented JSONP on the API backend. See the Wikipedia article for a brief overview. Our JSONP parameter is "callback". This parameter will not be used during signature calculation.

Authentication

In order to ensure the security of your data, the Mixpanel API requires a basic system of authentication.

Note: Our previously-used authentication method is deprecated. Please see further in this section for information on the old method.

Required parameter

api_secret - This can be found by clicking on your name in the upper righthand corner under Project Settings.

Authorization steps

The Data Export API accepts Basic access authentication over HTTPS as an authorization method. To make an authorized request, put your project's API Secret in the "username" field of the Basic access authentication header. Make sure you use HTTPS and not HTTP - our API rejects requests made over HTTP, since this sends your API Secret over the internet in plain text.

Examples

Here's an example of a properly-authenticated request made with cURL:

curl https://mixpanel.com/api/2.0/segmentation/ -u : -d from_date="2016-02-11" -d to_date="2016-02-11" -d event="Viewed Page"

You can also make a request in your browser:

https://api_secret@mixpanel.com/api/2.0/segmentation?from_date=2016-02-11&to_date=2016-02-11&event=Viewed Page

Deprecated Authentication

Note: This authentication method is deprecated. It is recommended that you use the current authentication method highlighted above.

Required parameters

api_key - This is an API key corresponding to the project you wish to consume from.

api_secret - This is a secret API key corresponding to the project. You should never give this out to anyone or show it.

sig - Signature for the method call, used in combination with your api_key, api_secret, and API endpoint parameters.

expire - UTC time in seconds; used to expire an API request.

Both api_key and api_secret can be found on your account page under API information.

Authorization steps

  1. All requests must have the following parameters: api_key, expire, sig.
  2. api_key can be found on your account page under API Information.
  3. expire is any UTC time in the future that represents how long you wish the request consuming data to last. For example, if you wish the request to only last 1 minute, you would calculate the UTC time as of now and then add 60 representing 1 minute ahead.
  4. Calculate the signature of the request using your api_secret. Calculating the signature is done in parts: sort the parameters you are including with the URL alphabetically, join into a string resulting in key=valuekey2=value2 (excluding ampersands), concatenate the result with the api_secret by appending it, and lastly md5 hash the final string.

    This hash is used for the sig parameter in the request therefore it should not be be calculated with sig as a parameter. The purpose of this process is to prevent unauthorized attempts to consume your data as much as possible.

    Pseudo code:

    args = all query parameters going to be sent out with the request
           (e.g. api_key, unit, interval, expire, format, etc.) excluding sig.
    
    args_sorted = sort_args_alphabetically_by_key(args)
    
    args_concat = join(args_sorted)
    
    # Output: api_key=ed0b8ff6cc3fbb37a521b40019915f18event=["pages"]
    #         expire=1248499222format=jsoninterval=24unit=hour
    
    sig = md5(args_concat + api_secret)
    
  5. Lastly, include sig with your URL request along with the normal parameters to consume data securely. Your URL should look similar to this however varying on the endpoint you are requesting data from:

    https://mixpanel.com/api/2.0/events/?interval=7&expire=1275624968&sig=046ceec93983811dad0fb20f842c351a&api_key=f0aa346688cee071cd85d857285a3464&type=average&event=%5B%22splash+features<%22%2C+%22account-page%22%5D&unit=day

Annotations

Method: annotations

URI: https://mixpanel.com/api/2.0/annotations/

Description:

List the annotations for the given date range.

from_date
string
The beginning of the date range to get annotations for in yyyy-mm-dd format. This date is inclusive.
to_date
string
The end of the date range to get annotations for in yyyy-mm-dd format. This date is inclusive.

Example URL:

https://mixpanel.com/api/2.0/annotations/?from_date=2014-05-11&to_date=2014-06-09

Return format:

{"annotations": [
    {"date": "2014-05-23 00:00:00", "project_id": 23880, "id": 148, "description": "Launched v2.0 of product"},
    {"date": "2014-05-29 00:00:00", "project_id": 23880, "id": 150, "description": "Streamlined registration process"}
], "error": false}

Method: create

URI: https://mixpanel.com/api/2.0/annotations/create/

Description:

Create a new annotation at the specified time.

date
string
The time in yyyy-mm-hh HH:MM:SS when you want to create the annotation at.
description
string
The annotation description.

Example URL:

https://mixpanel.com/api/2.0/annotations/create?date=2014-05-15+00%3A00%3A00&description=Launched+version+2.0!

Return format:

{"error": false}

Method: update

URI: https://mixpanel.com/api/2.0/annotations/update/

Description:

Update an annotation to the new time or description.

id
string
The ID of the annotation you wish to update.
date
string
The time in yyyy-mm-hh HH:MM:SS to update the annotation to.
description
string
The annotation description to update the annotation to.

Example URL:

https://mixpanel.com/api/2.0/annotations/update?id=148&date=2014-03-09+12%3A34%3A56&description=Concluded button A/B test.

Return format:

{"error": false}

Method: delete

URI: https://mixpanel.com/api/2.0/annotations/delete/

Description:

Delete an annotation.

id
string
The ID of the annotation to delete.

Example URL:

https://mixpanel.com/api/2.0/annotations/delete?id=42

Return format:

{"error": false}

Events

Method: events

URI: https://mixpanel.com/api/2.0/events/

Description:

Get unique, total, or average data for a set of events over N days, weeks, or months.

event
array
The event or events that you wish to get data for, encoded as a JSON array. Example format: "["play song", "log in", "add playlist"]"
type
string
The analysis type you would like to get data for - such as general, unique, or average events. Valid values: "general", "unique", or "average"
unit
string
This can be "minute", "hour", "day", "week", or "month". It determines the level of granularity of the data you get back. Note that you cannot get hourly uniques.
interval
integer
The number of "units" to return data for - minutes, hours, days, weeks, or months. 1 will return data for the current unit (minute, hour, day, week or month). 2 will return the current and previous units, and so on. Specify either interval or from_date and to_date.
from_date
string
The first date to return data for, in yyyy-mm-dd format. This date is inclusive. Specify either interval or from_date and to_date.
to_date
string
The last date to return data for, in yyyy-mm-dd format. This date is inclusive. Specify either interval or from_date and to_date.
format
string
The data return format, such as JSON or CSV. Options: "json" (default), "csv"

Example URL:

https://mixpanel.com/api/2.0/events/?interval=7&&type=average&event=%5B%22splash+features%22%2C+%22account-page%22%5D&unit=day

Return format:

{"data": {"series": ["2010-05-29",
                  "2010-05-30",
                  "2010-05-31",
                  ],
       "values": {"account-page": {"2010-05-30": 1,},
                  "splash features": {"2010-05-29": 6,
                                      "2010-05-30": 4,
                                      "2010-05-31": 5,
                                     }
                 }
     },
"legend_size": 2}

Method: top

URI: https://mixpanel.com/api/2.0/events/top/

Description:

Get the top events for today, with their counts and the normalized percent change from yesterday.

type
string
The analysis type you would like to get data for - such as general, unique, or average events. Valid values: "general", "unique", or "average"
limit
integer
The maximum number of events to return. Defaults to 100.

Example URL:

https://mixpanel.com/api/2.0/events/top?type=unique

Return format:

{"events": [{"amount": 2,
             "event": u"funnel",
             "percent_change": -0.35635745999582824},
            {"amount": 75,
             "event": u"pages",
             "percent_change": -0.20209602478821687},
            {"amount": 2, "event": u"projects", "percent_change": 1.0}],
 "type": u"unique"}

Method: names

URI: https://mixpanel.com/api/2.0/events/names/

Description:

Get a list of the most common events over the last 31 days.

type
string
The analysis type you would like to get data for - such as general, unique, or average events. Valid values: "general", "unique", or "average"
limit
integer
The maximum number of events to return. Defaults to 255.

Example URL:

https://mixpanel.com/api/2.0/events/names?type=general

Return format:

// Alphabetical Order, descending
[ "battle","click signup button","send message","View homepage"]

Event properties

Method: properties

URI: https://mixpanel.com/api/2.0/events/properties/

Description:

Get unique, total, or average data for of a single event and property over days, weeks, or months.

event
string
The event that you wish to get data for. Note: this is a single event name, not an array.
name
string
The name of the property you would like to get data for.
values
array
The specific property values that you would like to get data for, encoded as a JSON array. Example: If you have a property "gender" you may have values "male", "female" and "unknown". If you just want data for female and unknown users, you can include a values property that looks like "["female", "unknown"]"
type
string
The analysis type you would like to get data for - such as general, unique, or average events. Valid values: "general", "unique", or "average"
unit
string
This can be "minute", "hour", "day", "week", or "month". It determines the level of granularity of the data you get back. Note that you cannot get hourly uniques.
interval
integer
The number of "units" to return data for - minutes, hours, days, weeks, or months. 1 will return data for the current unit (minute, hour, day, week or month). 2 will return the current and previous units, and so on. Specify either interval or from_date and to_date.
from_date
string
The first date to return data for, in yyyy-mm-dd format. This date is inclusive. Specify either interval or from_date and to_date.
to_date
string
The last date to return data for, in yyyy-mm-dd format. This date is inclusive. Specify either interval or from_date and to_date.
format
string
The data return format, such as JSON or CSV. Options: "json" (default), "csv"
limit
integer
The maximum number of values to return. Defaults to 255.

Example URL:

https://mixpanel.com/api/2.0/events/properties?name=feature&interval=7&type=unique&event=splash+features&unit=day

Return format:

{"data": {"series": ["2010-05-29",
                     "2010-05-30",
                     "2010-05-31",
                     ],
          "values": {"splash features": {"2010-05-29": 6,
                                         "2010-05-30": 4,
                                         "2010-05-31": 5,
                                        }
                    }
        },
 "legend_size": 2}

Method: top

URI: https://mixpanel.com/api/2.0/events/properties/top/

Description:

Get the top property names for an event.

event
string
The event that you wish to get data for. Note: this is a single event name, not an array.
limit
integer
The maximum number of properties to return. Defaults to 10.

Example URL:

https://mixpanel.com/api/2.0/events/properties/top?event=splash+feature

Return format:

{"ad version": {"count": 295}, "user type": {"count": 91}}

Method: values

URI: https://mixpanel.com/api/2.0/events/properties/values/

Description:

Get the top values for a property.

event
string
The event that you wish to get data for. Note: this is a single event name, not an array.
name
string
The name of the property you would like to get data for.
limit
integer
The maximum number of events to return. Defaults to 255.

Example URL:

https://mixpanel.com/api/2.0/events/properties/values?name=feature&interval=7&type=general&event=splash+features&unit=day

Return format:

// Ordered by volume, descending
["male", "female", "unknown"]

Funnels

Method: funnels

URI: https://mixpanel.com/api/2.0/funnels/

Description:

Get data for a funnel.

funnel_id
integer
The funnel that you wish to get data for.
from_date
string
The first date in yyyy-mm-dd format from which a user can begin the first step in the funnel. This date is inclusive.
to_date
string
The last date in yyyy-mm-dd format from which a user can begin the first step in the funnel. This date is inclusive.
length
integer
The number of units (defined by length_unit) each user has to complete the funnel, starting from the time they triggered the first step in the funnel. May not be greater than 90 days. Note that we will query for events past the end of to_date to look for funnel completions. This defaults to the value that was previously saved in the UI for this funnel.
length_unit
string
The unit applied to the length parameter. Can be "second", "minute", "hour", or "day". Defaults to the value that was previously saved in the UI for this funnel.
interval
integer
The number of days you want your results bucketed into. The default value is 1.
unit
string
This is an alternate way of specifying interval and can be "day", "week", or "month".
on
string
The property expression to segment the event on. See the expression section below.
where
string
An expression to filter events by. See the expression section below.
limit
integer
Return the top limit property values. Defaults to 255 if not explicitly included. This parameter does nothing if "on" is not specified.

Example URL:

https://mixpanel.com/api/2.0/funnels/?funnel_id=1&unit=week

Return format:

{"meta": 
	{"dates": ["2016-09-12", "2016-09-19", "2016-09-26"]}, 
	"data": {
		"2016-09-12": 
			{"steps": [
				{"count": 32688, "step_conv_ratio": 1, "goal": "App Open", "overall_conv_ratio": 1, "avg_time": null, "event": "App Open"}, 
				{"count": 20524, "step_conv_ratio": 0.627875673029858, "goal": "Game Played", "overall_conv_ratio": 0.627875673029858, "avg_time": 718, "event": "Game Played"}], 
			"analysis": {"completion": 20524, "starting_amount": 32688, "steps": 2, "worst": 1}}, 
		"2016-09-19": 
			{"steps": [
				{"count": 32486, "step_conv_ratio": 1, "goal": "App Open", "overall_conv_ratio": 1, "avg_time": null, "event": "App Open"}, 
				{"count": 20809, "step_conv_ratio": 0.6405528535369082, "goal": "Game Played", "overall_conv_ratio": 0.6405528535369082, "avg_time": 698, "event": "Game Played"}], 
			"analysis": {"completion": 20809, "starting_amount": 32486, "steps": 2, "worst": 1}}, 
		"2016-09-26": 
			{"steps": [
				{"count": 16103, "step_conv_ratio": 1, "goal": "App Open", "overall_conv_ratio": 1, "avg_time": null, "event": "App Open"}, 
				{"count": 12679, "step_conv_ratio": 0.7873688132646091, "goal": "Game Played", "overall_conv_ratio": 0.7873688132646091, "avg_time": 571, "event": "Game Played"}], 
			"analysis": {"completion": 12679, "starting_amount": 16103, "steps": 2, "worst": 1}}
		}}

Method: list

URI: https://mixpanel.com/api/2.0/funnels/list/

Description:

Get the names and funnel_ids of your funnels. This method takes no parameters.

Example URL:

https://mixpanel.com/api/2.0/funnels/list

Return format:

[{"funnel_id": 7509, "name": "Signup funnel"},
{"funnel_id": 9070, "name": "Funnel tutorial"}]

Segmentation

Method: segmentation

URI: https://mixpanel.com/api/2.0/segmentation/

Description:

Get data for an event, segmented and filtered by properties.

event
string
The event that you wish to segment on.
from_date
string
The date in yyyy-mm-dd format from which to begin querying for the event from. This date is inclusive.
to_date
string
The date in yyyy-mm-dd format from which to stop querying for the event from. This date is inclusive.
on
string
The property expression to segment the event on. See the expressions section below.
unit
string
This can be "minute", "hour", "day", or "month". This determines the buckets into which the property values that you segment on are placed. The default value is "day".
interval
integer
Optional parameter in lieu of 'unit'. Determines the number of days your results are bucketed into. Can be used with or without 'from_date' and 'to_date' parameters.
where
string
An expression to filter events by. See the expressions section below.
limit
integer
Return the top limit property values. This parameter does nothing if "on" is not specified.
type
string
This can be "general", "unique", or "average". If this is set to "unique", we return the unique count of events or property values. If set to "general", we return the total, including repeats. If set to "average", we return the average count. The default value is "general".

Example 1

Suppose Harry Q. Bovik has a website named example.com. He has an event named signed up, sent whenever a user signs up to example.com. It has a string property named mp_country_code that stores the country code of the user signing up.

A query with the following GET parameters sent over HTTPS with your API Secret as the Basic Access Authentication username would return the number of signed up events for each day from 2011-08-06 to 2011-08-09:

Parameter
Value
event
signed up
from_date
2011-08-06
to_date
2011-08-09

Return format:

{"data": {"series": ["2011-08-08",
              "2011-08-09",
              "2011-08-06",
              "2011-08-07"],
   "values": {"signed up": {"2011-08-06": 147,
                            "2011-08-07": 146,
                            "2011-08-08": 776,
                            "2011-08-09": 1376}}},
"legend_size": 1}

Example 2

Suppose Harry is impressed with the number of signups on 2011-08-09, and now wants to know the top five countries his signups came from on that day. He can make the following query sent over HTTPS with your API Secret as the Basic Access Authentication username:

Parameter
Value
event
signed up
from_date
2011-08-09
to_date
2011-08-09
limit
5
on
properties["mp_country_code"]

Return format:

{"data": {"series": ["2011-08-09"],
   "values": {"CA": {"2011-08-09": 277},
              "FR": {"2011-08-09": 8},
              "GB": {"2011-08-09": 19},
              "IN": {"2011-08-09": 19},
              "US": {"2011-08-09": 1036}}},
"legend_size": 5}

Example 3

Harry now wants to zero in on the US and Canada. He is tracking a property named mp_keyword, which tells him the search keyword that users used to get to example.com. Now he wants to determine how many signups from the US and Canada came about as a result of a search that contained the word "harry." He can do that with the following query sent over HTTPS with your API Secret as the Basic Access Authentication username:

Parameter
Value
event
signed up
from_date
2011-08-09
to_date
2011-08-09
on
properties["mp_country_code"]
where
"harry" in properties["mp_keyword"] and ("CA" == properties["mp_country_code"] or "US" == properties["mp_country_code"])

Return format:

{"data": {"series": ["2011-08-09"],
   "values": {"CA": {"2011-08-09": 31},
              "US": {"2011-08-09": 312}}},
"legend_size": 2}

Note: Segmentation expressions with to_dates in the future will return inaccurate data.

Method: numeric

URI: https://mixpanel.com/api/2.0/segmentation/numeric/

Description:

Get data for an event, segmented and filtered by properties, with values placed into numeric buckets.

event
string
The event that you wish to segment on.
from_date
string
The date in yyyy-mm-dd format from which to begin querying for the event from. This date is inclusive.
to_date
string
The date in yyyy-mm-dd format from which to stop querying for the event from. This date is inclusive. The date range may not be more than 30 days.
on
string
The property expression to segment the event on. This expression must be a numeric property. See the expressions section below.
unit
string
This can be "hour" or "day". This determines the buckets into which the property values that you segment on are placed. The default value is "day".
where
string
An expression to filter events by. See the expressions section below.
type
string
This can be "general", "unique", or "average". If this is set to "unique", we return the unique count of events or property values. If it is set to "general", we return the total, including repeats. If this is set to "average", we return the unique count of events or property values divided by the general count. The default value is "general".

Example 1

Harry Q. Bovik also has an event named page loaded. It has a property named time that represents the time in milliseconds it took to load the page. Harry wants to see the distribution of page load times that are greater than 2000 milliseconds. But suppose Harry accidentally was sending the time property to Mixpanel as a string, so its the incorrect type. He can make the following query, sent over HTTPS with the API Secret as the Basic Access Authentication username, involving an explicit typecast to number to get the results he wants:

Parameter
Value
event
page loaded
from_date
2011-08-06
to_date
2011-08-09
on
number(properties["time"])
where
number(properties["time"]) >= 2000
buckets
5

Return format:

{"data": {"series": ["2011-08-08",
              "2011-08-09",
              "2011-08-06",
              "2011-08-07"],
   "values": {"2,000 - 2,100": {"2011-08-06": 1,
                                "2011-08-07": 5,
                                "2011-08-08": 4,
                                "2011-08-09": 15},
              "2,100 - 2,200": {"2011-08-07": 2,
                                "2011-08-08": 7,
                                "2011-08-09": 15},
              "2,200 - 2,300": {"2011-08-06": 1,
                                "2011-08-08": 6,
                                "2011-08-09": 5},
              "2,300 - 2,400": {"2011-08-06": 4,
                                "2011-08-08": 1,
                                "2011-08-09": 12},
              "2,400 - 2,500": {"2011-08-08": 2,
                                "2011-08-09": 5}}},
"legend_size": 5}

Method: sum

URI: https://mixpanel.com/api/2.0/segmentation/sum/

Description:

Sums an expression for events per unit time.

event
string
The event that you wish to segment on.
from_date
string
The date in yyyy-mm-dd format from which to begin querying for the event from. This date is inclusive.
to_date
string
The date in yyyy-mm-dd format from which to stop querying for the event from. This date is inclusive. The date range may not be more than 30 days.
on
string
The expression to sum per unit time. The result of the expression should be a numeric value. If the expression is not numeric, a value of 0.0 is assumed. See the expressions section below.
unit
string
This can be "hour" or "day". This determines the buckets into which the property values that you segment on are placed. The default value is "day".
where
string
An expression to filter events by. See the expressions section below.

Example 1

Harry also sells things from example.com. He has an event named item sold that tracks each item that gets sold from his website. It has a number property named price that records the value of the item being sold. He has another number property named overhead that represents the overhead cost of the item. Harry can find out how much profit he is making each day with the following query, sent over HTTPS with the API Secret as the Basic Access Authentication username:

Parameter
Value
event
item sold
from_date
2011-08-06
to_date
2011-08-09
on
properties["price"] - properties["overhead"]

Return format:

{"results": {"2011-08-06": 376.0,
      "2011-08-07": 634.0,
      "2011-08-08": 474.0,
      "2011-08-09": 483.0},
"status": "ok"}

Method: average

URI: https://mixpanel.com/api/2.0/segmentation/average/

Description:

Averages an expression for events per unit time.

event
string
The event that you wish to segment on.
from_date
string
The date in yyyy-mm-dd format from which to begin querying for the event from. This date is inclusive.
to_date
string
The date in yyyy-mm-dd format from which to stop querying for the event from. This date is inclusive. The date range may not be more than 30 days.
on
string
The expression to sum per unit time. The result of the expression should be a numeric value. If the expression is not numeric, a value of 0.0 is assumed. See the expressions section below.
unit
string
This can be "hour" or "day". This determines the buckets into which the property values that you segment on are placed. The default value is "day".
where
string
An expression to filter events by. See the expressions section below.

Example 1

Instead of finding out the total profit he is making per day by selling things from his website, Harry can also find out the average price of an item being sold with the following query, sent over HTTPS with the API Secret as the Basic Access Authentication username:

Parameter
Value
event
item sold
from_date
2011-08-06
to_date
2011-08-09
on
properties["price"]

Return format:

{"results": {"2011-08-06": 8.64705882352939,
      "2011-08-07": 4.640625,
      "2011-08-08": 3.6230899830221,
      "2011-08-09": 7.3353658536585},
"status": "ok"}

Segmentation expressions

The power of segmentation comes from the ability to define custom expressions based on property names in the where and on parameters. An expression consists of a property, combined with one or more operators that can perform mathematical operations, logical operations, or typecasts. Expression are then applied in the where and on parameters of the segmentation API. The full grammar for expressions is given here:

<expression> ::= 'properties["' <property> '"]'
                | <expression> <binary op> <expression>
                | <unary op> <expression>
                | <math op> '(' <expression> ')'
                | <typecast op> '(' <expression> ')'
                | '(' <expression> ')'
                | <boolean literal>
                | <numeric literal>
                | <string literal>
  <binary op> ::= '+' | '-' | '*' | '/' | '%' | '==' | '!=' |
                  '>' | '>=' | '<' | '<=' | 'in' | 'and' | 'or'
   <unary op> ::= '-' | 'not'
    <math op> ::= 'floor' | 'round' | 'ceil'
<typecast op> ::= 'boolean' | 'number' | 'string'
   <property> ::= 'properties["' <property name> '"]'

A great way to build segmentation expressions is via examining the segmentation requests made within our own Segmentation report! Click here to learn more.

Typecast Operations

Internally, all properties of events have a type. This type is determined when we parse the event sent to us into a JSON object. Currently, there are three types, string, number, and boolean, which may be specified directly. A property may also have the values null and undefined, which are only handled internally. The default type is string. If you wish to treat an expression as another type, you may use the typecast operators to cast a property to a different type. For example, if properties["signed up"] has values of "true" and "false" as strings, and you wish to intercodet them as booleans, you may cast them by using the boolean() typecast function: boolean(properties["signed up"]).

The typecasting rules are described below.

Casting to String

Type
Result
String
Same string
Number
String containing the decimal representation of the number.
Boolean
"true" or "false"
null
null
undefined
undefined

Casting to Number

Type
Result
String
Attempts to interpret the string as a decimal. If this fails, the value becomes undefined.
Number
Same number
Boolean
1.0 if true, 0.0 if false
null
undefined
undefined
undefined

Casting to Boolean

Type
Result
String
"true", "1", "yes" evaluates to true; "false", "0", "no" evaluates to false
Number
false if 0, true otherwise
Boolean
Same boolean
null
false
undefined
false

Binary Operations

The arithmetic operators "-", "*", "/", "%" perform the subtraction, multiplication, division, and remainder operations, respectively. The division operator will return undefined if the divisor is 0. The sign of the value of the remainder will be equivalent to the dividend. All four of these operators expect both operands to be of the type number, or else the result is undefined.

The "+" operator behaves as addition if its two operands are of type number. However, if its two operands are of type string, it will concatenate the two strings. In other cases, the result is undefined.

The equals operator "==" will always return a boolean. When its two types are equal, it performs the standard equality comparison based on the values. If the types of its operands are not equal, false is returned. The not equals operator "!=" returns false when the equals operator would return true and vice-versa.

The comparison operators ">", ">=", "<", and "<=" returns a boolean value based on evaluating the comparison when its operands are both of type number. When its types are not equal, undefined is returned.

The "in" operator returns true if both operands are of type string and the first string is a substring of the second. When both operands are of differing types, undefined is returned.

The logical operators "and" and "or" accept boolean and undefined operands. An operand with type undefined evaluates as false. Any other types will result in an error.

Unary and Math Operations

The "-" operator will negate an operand of type number, and return undefined otherwise.

The "not" operator will perform the logical not on an operand of type boolean. It will also evaluate an operand of type undefined as true. All other operands will be evaluated to undefined.

The "floor", "round", and "ceil" functions perform their mathematical operations on an operand of type number. On all other types, it will return undefined.

Retention

Method: retention

URI: https://mixpanel.com/api/2.0/retention/

Description:

Get cohort analysis.

from_date
string
The date in yyyy-mm-dd format from which to begin generating cohorts from. This date is inclusive.
to_date
string
The date in yyyy-mm-dd format from which to stop generating cohorts from. This date is inclusive.
retention_type
string
Must be either "birth" or "compounded". Defaults to "birth".
born_event
string
The first event a user must do to be counted in a birth retention cohort. Required when retention_type is "birth"; ignored otherwise.
event
string
The event to generate returning counts for. Applies to both birth and compounded retention. If not specified, we look across all events.
born_where
string
An expression to filter born_events by. See the expressions section above.
where
string
An expression to filter the returning events by. See the expressions section above.
interval
integer
The number of days you want your results bucketed into. May not be greater than 90 days. The default value is 1 or specified by unit.
interval_count
integer
The number of intervals you want; defaults to 1. Note that we include a "0th" interval for events which take place less than one interval after the initial event.
unit
string
This is an alternate way of specifying interval and can be "day", "week", or "month".
on
string
The property expression to segment the second event on. See the expressions section above.
limit
integer
Return the top limit segmentation values. This parameter does nothing if "on" is not specified.

Example URL:

https://mixpanel.com/api/2.0/retention/?from_date=2012-01-01&to_date=2012-01-03&retention_type=birth&interval_count=2&event=viewed+report&born_event=event+integration&expire=1326512270&sig=2bdfb7fe5db9337f357e04f7d1a85b86

Return format:

{
    "2012-01-01": {
        "counts": [2, 1, 2], "first": 2
    },
    "2012-01-02": {
        "counts": [9, 7, 6], "first": 10
    },
    "2012-01-03": {
        "counts": [9, 6, 4], "first": 10
    }
}

We specified neither an interval nor a unit, so the interval is 1 day. This means that each user gets 24 hours in each interval to do the specified event. On 2012-01-02, 10 people did the born_event ("event integration"), as indicated by the first field. If the retention_type=compounded, then first will instead indicate the number of people who did event ("viewed report") on the specified date. 9 of those people did event ("viewed report") within 24 hours (the "0th" interval) of doing the born_event . 7 of those did event between 24 and 48 hours (interval 1) of the born_event. These 7 are a subset of the initial 10, but not necessarily a subset of the 9 (retention is not a funnel; see the number increase between 72 and 96 hours). And finially, 6 people did event between 48 and 72 hours (interval 2) after the born_event.

In the Mixpanel retention UI, "First time" corresponds to retention_type=birth, and "Recurring" corresponds to retention_type=compounded.

Method: addiction

URI: https://mixpanel.com/api/2.0/retention/addiction/

Description:

Get data about how frequently people are performing events.

from_date
string
The date in yyyy-mm-dd format from which to begin generating cohorts from. This date is inclusive.
to_date
string
The date in yyyy-mm-dd format from which to stop generating cohorts from. This date is inclusive.
unit
string
The overall time period to return frequency of actions for. Can be "day", "week", or "month".
addiction_unit
string
The granularity to return frequency of actions at. Can be "hour" or "day".
event
string
The event to generate returning counts for.
where
string
An expression to filter the returning events by. See the expressions section above.
on
string
The property expression to segment the second event on. See the expressions section above.
limit
integer
Return the top limit segmentation values. This parameter does nothing if "on" is not specified.

Example URL:

https://mixpanel.com/api/2.0/retention/addiction?unit=day&from_date=2012-01-01&to_date=2012-01-03&event=Viewed+report&addiction_unit=hour

Return format:

{
    "2012-01-01": [305, 107, 60, 41, 32, 20, 12, 7, 4, 3, 3, 3, 2, 2, 2, 1, 1, 1, 1, 1, 1, 1, 1, 1],
    "2012-01-02": [495, 204, 117, 77, 53, 36, 26, 20, 12, 7, 4, 3, 3, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0],
    "2012-01-03": [671, 324, 176, 122, 81, 63, 48, 31, 21, 14, 9, 5, 3, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0]
}

We specified "day" as unit and "hour" as addiction_unit, so one day"s worth of data is shown for each date, split into hours. On 2012-01-02, 495 people did the event ("Viewed report") during at least 1 hour out of the next 24 hour period (the period specified by "unit"). 204 people did the event during at least 2 hours. 117 people did the event during at least 3 hours.

Engage

Method: engage

URI: https://mixpanel.com/api/2.0/engage/

Description:

Query People Data.

where
string
An expression to filter people by. See the expressions section above.
session_id
string
A string id provided in the results of a previous query. Using a session_id speeds up api response, and allows paging through results.
page
integer
Which page of the results to retrieve. Pages start at zero. If the "page" parameter is provided, the session_id parameter must also be provided.

Return format:

{"page": 0,
 "page_size": 1000,
 "results": [{"$distinct_id": 4,
              "$properties": {"$created": "2008-12-12T11:20:47",
                              "$email": "example@mixpanel.com",
                              "$first_name": "Example",
                              "$last_name": "Name",
                              "$last_seen": "2008-06-09T23:08:40",}}],
 "session_id": "1234567890-EXAMPL",
 "status": "ok",
 "total": 1}

Api responses will return at most page_size records for each request. To request additional records, callers should repeat their call to the api using the same where param, but provide a session_id parameter with a value taken from the first response, and include a page parameter with a value one greater than the value of page in the response.

A caller trying to retrieve all of the records for a particular query might use an algorithm something like this:

# Get the first page of data associated with our selector expression
this_page = query_api(where=YOUR_SELECTOR_EXPRESSION)
do_something_with_response(this_page)

# If we get fewer records than the page_sized returned with our results,
# then there are no more records to get. Otherwise, keep querying for additional pages.
while (length of this_page.results) >= this_page.page_size:
    next_page_number = this_page.page + 1
    this_page = query_api(where=YOUR_SELECTOR_EXPRESSION, session_id=this_page.session_id, page=next_page_number)
    do_something_with_response(this_page)

API errors

Error format

{"error": "Invalid parameter: unit",
 "request": "/api/2.0/events/general?interval=7&event=%5B%22splash+features%22%5D&unit=day"}

Error table

Error
Description
Missing required parameter: X
The API method you are calling requires parameter X.
Invalid parameter: X
Parameter is not of the expected type or is malformed.
Invalid JSON Format: X
Parameter X is not properly JSON encoded.
Invalid endpoint: X
You are requesting an endpoint that does not exist.
Invalid date range
The date range you have specified is not 30 days or less.
Query Error in selector, X
The selector you supplied, most likely in a where clause, has an error.
Query Error in action, X
The action you supplied has an error.
Document Sections