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

Data Export API

Updated Jan. 13, 2014

Getting data back out with the 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.

API Information

Basic information regarding the Mixpanel API

Client Libraries

Authentication

API endpoints

Each type of analysis has its own endpoint and methods. Please note, the format parameter at this time is required and only supports json as a value at this time.

Export

  • export - get a "raw dump" of tracked events over a time period

Events

  • events - get total, unique, or average data for a set of events over a time period
  • top - get the top events from the last day
  • names - get the top event names for a time period

Event Properties

  • properties - get total, unique, or average data from a single event property
  • top - get the top properties for an event
  • values - get the top values for a single event property

Funnels

  • funnels - get data for a set of funnels over a time period
  • list - get a list of the names of all the funnels

Segmentation

  • segmentation - get data for an event, segmented and filtered by properties over a time period
  • numeric - get numeric data, divided up into buckets for an event segmented and filtered by properties over a time period
  • sum - get the sum of a segment's values per time unit
  • average - get the average of a segment's values per time unit
  • Segmentation Expressions - a detailed overview of what a segmentation expression consists of

Retention

  • retention - get data about how often people are coming back (cohort analysis)

People Analytics

  • engage - get data from People Analytics

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 respository
Option 2: mixpanel-api (Customer contributed)

Javascript
We do not have a JS 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 in order consume your data.

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 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:

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

Events

Method: events

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

Description

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

Parameters

Required Name Type Description
required 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"]'

required 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'

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

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

optional format string

The data return format, such as JSON or CSV.

Options: 'json' (default), 'csv'

Example URL

http://mixpanel.com/api/2.0/events/?interval=7&expire=1275624968&sig=046ceec93983811dad0fb20
f842c351a&api_key=f0aa346688cee071cd85d857285a3464&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: http://mixpanel.com/api/2.0/events/top/

Description

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

Parameters

Required Name Type Description
required 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'

optional limit integer

The maximum number of events to return. Defaults to 100. The maximum this value can be is 100.

Example URL

http://mixpanel.com/api/2.0/events/top?sig=02e38a843297d188ee73779ab872cc1e&api_key=
f0aa346688cee071cd85d857285a3464&type=unique&expire=1275627103

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: http://mixpanel.com/api/2.0/events/names/

Description

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

Parameters

Required Name Type Description
required 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'

optional limit integer

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

Example URL

http://mixpanel.com/api/2.0/events/names?expire=1275627103&sig=9f2a0f7024b
6426aa440cf3ecad66165&api_key=f0aa346688cee071cd85d857285a3464&type=general

Return format

// Ordered by volume, descending
['View homepage', 'click signup button', 'battle', 'send message']

Event Properties

Method: properties

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

Description

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

Parameters

Required Name Type Description
required event string

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

required name string

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

optional 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"]'

required 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'

required 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

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

optional format string

The data return format, such as JSON or CSV.

Options: 'json' (default), 'csv'

optional limit integer

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

Example URL

http://mixpanel.com/api/2.0/events/properties?name=feature&interval=7&expire=1275678109&
sig=e0c4bb0c5ead7aeb4cf9b1682e0599a3&api_key=f0aa346688cee071cd85d857285a3464&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: http://mixpanel.com/api/2.0/events/properties/top/

Description

Get the top property names for an event.

Parameters

Required Name Type Description
required event string

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

optional limit integer

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

Example URL

http://mixpanel.com/api/2.0/events/properties/top?expire=1275678109&sig=ce1930
e14e44db542409686a89bf03ef&api_key=f0aa346688cee071cd85d857285a3464&event=splash+feature

Return format

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

Method: values

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

Description

Get the top values for a property.

Parameters

Required Name Type Description
required event string

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

required name string

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

optional limit integer

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

optional bucket string

[Platform] - the specific data bucket you would like to query.

Example URL

http://mixpanel.com/api/2.0/events/properties/values?name=feature&interval=7&expire=12756841
78&sig=9733ee416d27bf27013c0bfde5227055&api_key=f0aa346688cee071cd85d857285a3464&
type=general&event=splash+features&unit=day

Return format

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

Funnels

Method: funnels

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

Description

Get data for a funnel.

Parameters

Required Name Type Description
required funnel_id integer

The funnel that you wish to get data for (passed back from list).

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

optional 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. The date range may not be more than 60 days.

optional length integer

The number of days each user has to complete the funnel, starting from the time they triggered the first step in the funnel. May not be greater than 60 days. Note that we will query for events past the end of to_date to look for funnel completions.

The default value is 14.

optional interval integer

The number of days you want your results bucketed into.

The default value is 1.

optional unit string

This is an alternate way of specifying interval and can be 'day' or 'week'.

optional on string

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

optional where string

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

optional limit integer

Return the top limit property values. This parameter does nothing if 'on' is not specified.

Example URL

http://mixpanel.com/api/2.0/funnels/?funnel_id=1&expire=1275687370&sig=0446b1725ffedf241f7bf3d2097af162
&api_key=f0aa346688cee071cd85d857285a3464&unit=week

Return format

{'Signup flow': {'data': {'2010-05-24': {'analysis': {'completion': 0.064679359580052493,
                                               'starting_amount': 762,
                                               'steps': 3,
                                               'worst': 2},
                                  'steps': [{'count': 762,
                                             'goal': 'pages',
                                             'overall_conv_ratio': 1.0,
                                             'step_conv_ratio': 1.0},
                                            {'count': 69,
                                             'goal': 'View signup',
                                             'overall_conv_ratio': 0.09055118110236221,
                                             'step_conv_ratio': 0.09055118110236221},
                                            {'count': 10,
                                             'goal': 'View docs',
                                             'overall_conv_ratio': 0.064679359580052493,
                                             'step_conv_ratio': 0.7142857142857143}]},
                   '2010-05-31': {'analysis': {'completion': 0.12362030905077263,
                                               'starting_amount': 906,
                                               'steps': 2,
                                               'worst': 2},
                                  'steps': [{'count': 906,
                                             'goal': 'homepage',
                                             'overall_conv_ratio': 1.0,
                                             'step_conv_ratio': 1.0},
                                            {'count': 112,
                                             'goal': 'View signup',
                                             'overall_conv_ratio': 0.12362030905077263,
                                             'step_conv_ratio': 0.12362030905077263}]}},
          'meta': {'dates': ['2010-05-24', '2010-05-31']}}}

Method: list

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

Description

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

Example URL

http://mixpanel.com/api/2.0/funnels/list?api_key=f0aa346688cee071cd85d857285a3464&
sig=775573914d02cf618de0d545584dfdc9&expire=1275687367

Return format

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

Segmentation

Method: segmentation

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

Description

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

Parameters

Required Name Type Description
required event string

The event that you wish to segment on.

required from_date string

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

required to_date string

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

optional on string

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

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

optional where string

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

optional limit integer

Return the top limit property values. This parameter does nothing if 'on' is not specified.

optional 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 would return the number of signed up events for each day from 2011-08-06 to 2011-08-09:
Parameter Value
api_key 538a3541010a82e649f31ab0ec3c01e8
sig d5fed3020049ba1dbea5ab22a22b0f8b
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:
Parameter Value
api_key 538a3541010a82e649f31ab0ec3c01e8
sig 25fb8805c1c3189a5c82a77b4374bba1
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:
Parameter Value
api_key 538a3541010a82e649f31ab0ec3c01e8
sig bde0cab26a675195c807e3b516b1024d
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: http://mixpanel.com/api/2.0/segmentation/numeric/

Description

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

Parameters

Required Name Type Description
required event string

The event that you wish to segment on.

required from_date string

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

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

required on string

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

required buckets integer

The number of buckets that you wish to divide the numeric values up into. We automatically compute the bucket ranges based on the maximum and minimum of your 'on' expression.

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

optional where string

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

optional 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 involving an explicit typecast to number to get the results he wants:
Parameter Value
api_key 538a3541010a82e649f31ab0ec3c01e8
sig 78417c45c5da8c9a51a6c7a7ddf72c9e
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: http://mixpanel.com/api/2.0/segmentation/sum/

Description

Sums an expression for events per unit time.

Parameters

Required Name Type Description
required event string

The event that you wish to segment on.

required from_date string

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

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

required 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 expression section below.

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

optional where string

An expression to filter events by. See the expression 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:
Parameter Value
api_key 538a3541010a82e649f31ab0ec3c01e8
sig 01000453fb4a7817b6cbbf8a153b6915
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: http://mixpanel.com/api/2.0/segmentation/average/

Description

Averages an expression for events per unit time.

Parameters

Required Name Type Description
required event string

The event that you wish to segment on.

required from_date string

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

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

required on string

The expression to average 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.

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

optional 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:
Parameter Value
api_key 538a3541010a82e649f31ab0ec3c01e8
sig 36ef4baf91a9ad6ca736801206760692
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> '"]'

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: http://mixpanel.com/api/2.0/retention/

Description

Get cohort analysis.

Parameters

Required Name Type Description
required from_date string

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

required to_date string

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

optional retention_type string

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

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.

optional event string

The event to generate returning counts for. Applies to both birth and compounded retention. If not specified, we look across all events.

optional born_where string

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

optional where string

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

optional interval integer

The number of days you want your results bucketed into.

The default value is 1 or specified by unit.

optional interval_count integer

The number of intervals you want; defaults to 1.

optional unit string

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

optional on string

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

optional limit integer

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

Example URL

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

Return format

{
    "2012-01-01": {
        "counts": [2, 1, 2, 1], "first": 2
    },
    "2012-01-02": {
        "counts": [9, 7, 6, 7], "first": 10
    },
    "2012-01-03": {
        "counts": [9, 6, 4, 3], "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 second event. On 2012-01-02, 10 people did the born_event ('event integration'). 9 of those people did the second event ('viewed report') within 24 hours of doing the born_event. 7 of those did the second event between 24 and 48 hours 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).

API Errors

Error format

{'error': 'Invalid parameter: unit',
 'request': '/api/2.0/events/general?interval=7&expire=1275712553&
             sig=7099abd62437c2ab6b82b45541730113&api_key=f0aa346688cee071cd85d857285a3464&
             event=%5B%22splash+features%22%5D&unit=dayy'}

Error table

Error Description
Invalid API key You may have forgotten to include your API key. Check your account page for the correct key.
Invalid request signature The signature you sent does not match the signature we generated to test against.
Expired request The request is past its expiration date (default 10 minutes).
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.

Engage

Method: engage

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

Description

Query People Data.

Parameters

Required Name Type Description
optional where string

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

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

optional 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)