Export Formatted Data

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.

Note that the timestamps Mixpanel stores look like unix timestamps, but are actually the result of offsetting the unix timestamp based on project timezone at ingestion time.

Client Libraries

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

  • Python
  • PHP
  • Ruby
  • We do not have a JavaScript client library, but we have implemented JSONP on the API backend. 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 YOUR_API_SECRET: \
    -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.

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)
  1. 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=dayt

Annotations

The following methods can be used to annotate the request.


annotations

List the annotations for the given date range.

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

Parameter
Type
Description

from_date

string
required

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

to_date

string
required

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

https://mixpanel.com/api/2.0/annotations/?from_date=2014-05-11&to_date=2014-06-09
{"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}


create

Create a new annotation at the specified time.

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

date

string
required

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

description

string
required

The annotated description.

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


update

Update an annotation to the new time or description.

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

Parameter
Type
Description

id

string
required

The ID of the annotation you wish to update.

date

string
required

The time in yyyy-mm-hh HH:mm:SS to update the annotation to.

description

string
required

The annotation description to update the annotation to.

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


delete

Delete an annotation.

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

Parameter
Type
Description

id

string
required

The ID of the annotation to delete.

https://mixpanel.com/api/2.0/annotations/delete?id=42
{"error": false}

Events

The following methods can be used to specify the event data exported from Mixpanel.


events

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

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

Parameter
Type
Description

event

array
required

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
required

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
required

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
optional

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

integer
optional

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
optional

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
optional

The data return format, such as JSON or CSV. Options: "json" (default), "csv".

https://mixpanel.com/api/2.0/events/?interval=7&&type=average&event=%5B%22splash+features%22%2C+%22account-page%22%5D&unit=day
{"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}


top

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

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

Parameter
Type
Description

type

string
required

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
optional

The maximum number of events to return. Defaults to 100.

https://mixpanel.com/api/2.0/events/top?type=unique
{"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"}


names

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

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

Parameter
Type
Description

type

string
required

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
optional

The maximum number of events to return. Defaults to 255.

https://mixpanel.com/api/2.0/events/names?type=general
// Alphabetical Order, descending
[ "battle","click signup button","send message","View homepage"]

Event Properties

The following methods can be used to specify the event properties exported from Mixpanel.


properties

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

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

Parameter
Type
Description

event

string
required

The event that you wish to get data for. Note: this is a single event name, not an array.

name

string
required

The name of the property you would like to get data for.

values

array
optional

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
required

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
required

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
optional

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
optional

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.

to_date

string
optional

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
optional

The data return format, such as JSON or CSV. Options: "json" (default), "csv".

limit

integer
optional

The maximum number of values to return. Defaults to 255.

https://mixpanel.com/api/2.0/events/properties?name=feature&interval=7&type=unique&event=splash+features&unit=day
{"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}


top

Get the top property names for an event.

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

Parameter
Type
Description

event

string
required

The event that you wish to get data for. Note: this is a single event name, not an array.

limit

integer
optional

The maximum number of properties to return. Defaults to 10.

https://mixpanel.com/api/2.0/events/properties/top?event=splash+feature
{"ad version": {"count": 295}, "user type": {"count": 91}}


values

Get the top values for a property.

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

Name
Type
Description

event

string
required

The event that you wish to get data for. Note: this is a single event name, not an array.

name

string
required

The name of the property you would like to get data for.

limit

integer
optional

The maximum number of events to return. Defaults to 255. Maximum value 10,000.

https://mixpanel.com/api/2.0/events/properties/values?name=feature&interval=7&type=general&event=splash+features&unit=day
["male", "female", "unknown"]

Funnels

The following methods return Mixpanel funnel data.


funnels

Get data for a funnel.

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

Parameter
Type
Description

funnel_id

integer
required

The funnel that you wish to get data for.

from_date

string
optional

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
optional

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
optional

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
optional

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
optional

The number of days you want each bucket to contain. The default value is 1.

unit

string
optional

This is an alternate way of specifying interval and can be "day", "week", or "month".

on

string
optional

The property expression to segment the event on. See the expression section below.

where

string
optional

An expression to filter events by. See the expression section below.

limit

integer
optional

Return the top property values. Defaults to 255 if not explicitly included. Maximum value 10,000. This parameter does nothing if "on" is not specified.

https://mixpanel.com/api/2.0/funnels/?funnel_id=1&unit=week
{"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}}
		}}


list

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

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

https://mixpanel.com/api/2.0/funnels/list
[{"funnel_id": 7509, "name": "Signup funnel"},
{"funnel_id": 9070, "name": "Funnel tutorial"}]

Segmentation

The following methods return Mixpanel segmentation data.


segmentation

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

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

Parameter
Type
Description

event

string
required

The event that you wish to segment on.

from_date

string
required

The date in yyyy-mm-dd format from which to begin querying for the event from. This date is inclusive.

to_date

string
required

The date in yyyy-mm-dd format from which to stop querying for the event from. This date is inclusive.

on

string
optional

The property expression to segment the event on. See the expressions section below.

unit

string
optional

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

Optional parameter in lieu of 'unit' when 'type' is not 'general'. Determines the number of days your results are bucketed into. Can be used with or without 'from_date' and 'to_date' parameters.

where

string
optional

An expression to filter events by. See the expressions section below.

limit

integer
optional

Return the top property values. Defaults to 60. Maximum value 10,000. This parameter does nothing if "on" is not specified.

type

string
optional

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

https://mixpanel.com/api/2.0/segmentation/?event=signed-up&from_date=2011-08-06&to_date=2011-08-09
{"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}


numeric

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

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

Parameter
Type
Description

event

string
required

The event that you wish to segment on.

from_date

string
required

The date in yyyy-mm-dd format from which to begin querying for the event from. This date is inclusive.

to_date

string
required

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
required

The property expression to segment the event on. This expression must be a numeric property. See the expressions section below.

unit

string
optional

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
optional

An expression to filter events by. See the expressions section below.

type

optional
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".

curl https://mixpanel.com/api/2.0/segmentation/numeric?event=signed_up&from_date=2011-08-09&to_date=2011-08-09&on=number(properties["time"])&where=number(properties["time"]) >= 2000&buckets=5
	-u YOUR_API_SECRET
{"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}


sum

Sums an expression for events per unit time.

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

Parameter
Type
Description

event

string
required

The event that you wish to segment on.

from_date

string
required

The date in yyyy-mm-dd format from which to begin querying for the event from. This date is inclusive.

to_date

string
required

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
required

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
optional

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
optional

An expression to filter events by. See the expressions section below.

curl https://mixpanel.com/api/2.0/segmentation/average?event=item_sold&from_date=2011-08-09&to_date=2011-08-09&on=(properties["price"])
	-u YOUR_API_SECRET
{"results": {"2011-08-06": 8.64705882352939,
      "2011-08-07": 4.640625,
      "2011-08-08": 3.6230899830221,
      "2011-08-09": 7.3353658536585},
"status": "ok"}


average

Averages an expression for events per unit time.

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

event

string
required

The event that you wish to segment on.

from_date

string
required

The date in yyyy-mm-dd format from which to begin querying for the event from. This date is inclusive.

to_date

string
required

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
required

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

courier">string
optional

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

courier">string
optional

An expression to filter events by. See the expressions section below.

{"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 intercode 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

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


retention

Get cohort analysis.

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

Parameter
Name
Type

from_date

string
required

The date in yyyy-mm-dd format from which to begin generating cohorts from. This date is inclusive.

to_date

string
required

The date in yyyy-mm-dd format from which to stop generating cohorts from. This date is inclusive.

retention_type

string
optional

Must be either "birth" or "compounded". Defaults to "birth".

born_event

string
optional

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
optional

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
optional

An expression to filter born_events by. See the expressions section above.

where

string
optional

An expression to filter born_events by. See the expressions section above.

interval

integer
optional

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
optional

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
optional

This is an alternate way of specifying interval and can be "day", "week", or "month".

on

string
optional

The property expression to segment the second event on. See the expressions section above.

limit

integer
optional

Return the top limit segmentation values. This parameter does nothing if "on" is not specified.

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
{
    "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. Seven 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 finally, 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.


addiction

Get data about how frequently people are performing events.

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

Parameter
Type
Description

from_date

string
required

The date in yyyy-mm-dd format from which to begin generating cohorts from. This date is inclusive.

to_date

string
required

The date in yyyy-mm-dd format from which to stop generating cohorts from. This date is inclusive.

unit

string
required

The overall time period to return frequency of actions for. Can be "day", "week", or "month".

addiction_unit

string
required

The granularity to return frequency of actions at. Can be "hour" or "day".

event

string
optional

The event to generate returning counts for.

where

string
optional

An expression to filter the returning events by. See the expressions section above.

on

string
optional

The property expression to segment the second event on. See the expressions section above.

limit

integer
optional

Return the top limit segmentation values. This parameter does nothing if "on" is not specified.

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
{
    "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


engage

Query People Data.

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

Parameter
Type
Description

where

string
required

An expression to filter people by. See the expressions section above.

session_id

string
optional

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
optional

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.

behaviors

integer
optional

If you are exporting people profiles using an event selector, you use a behaviors parameter in your request.

as_of_timestamp

integer
optional

If you try to export more than 1k profiles using a behaviors parameter and you don't included the parameter as_of_timestamp, you'll see the following error:

request for page in uncached query for params

{"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.