Data API

This document is for Version 2 of the Data API. Documentation for Version 1 (deprecated) can be found here.

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.

Beta: The Data API is still under development, please let us know if you are using it so we can keep you updated with any changes.

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.

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
  • retention
    get the retention data for a set of events

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
  • names
    get the names of all active funnels
  • dates
    get the dates in which a set of funnels were seen

Funnel Properties

  • properties
    get data for a single funnel property
  • names
    get the top property names for a funnel

API Errors back to top

Client Libraries back to top

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
We don't have a Ruby library for API v2.0 yet, but there is one for 1.0 that you could easily modify:
Visit the Ruby respository

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 back to top

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, 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 back to top

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

RequiredNameTypeDescription
requiredeventarray

The event or events that you wish to get data for, encoded as a JSON array.

Example format: '["play song", "log in", "add playlist"]'

requiredtypestring

The analysis type you would like to get data for - such as general, unique, or average events.

Valid values: 'general', 'unique', or 'average'

requiredunitstring

This can be 'hour', 'day', 'week', or 'month'.

It determines the level of granularity of the data you get back.

requiredintervalinteger

The number of "units" to return data for - hours, days, weeks, or months.

1 will return data for the current unit (hour, day, week or month). 2 will return the current and previous units, and so on.

optionalformatstring

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 back to 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

RequiredNameTypeDescription
requiredtypestring

The analysis type you would like to get data for - such as general, unique, or average events.

Valid values: 'general', 'unique', or 'average'

optionallimitinteger

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

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 back to top

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

Description

Get a list of the most common events over the last N days, weeks, or months.

Parameters

RequiredNameTypeDescription
requiredtypestring

The analysis type you would like to get data for - such as general, unique, or average events.

Valid values: 'general', 'unique', or 'average'

requiredunitstring

This can be 'hour', 'day', 'week', or 'month'.

It determines the level of granularity of the data you get back.

requiredintervalinteger

The number of "units" to return data for - hours, days, weeks, or months.

1 will return data for the current unit (hour, day, week or month). 2 will return the current and previous units, and so on.

optionallimitinteger

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

Example URL

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

Return format

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

Method: retention back to top

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

Description

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

Parameters

RequiredNameTypeDescription
requiredeventarray

The event or events that you wish to get data for, encoded as a JSON array.

Example format: '["play song", "log in", "add playlist"]'

requiredtypestring

The analysis type you would like to get data for - such as general, unique, or average events.

Valid values: 'general', 'unique', or 'average'

requiredunitstring

This can be 'hour', 'day', 'week', or 'month'.

It determines the level of granularity of the data you get back.

requiredintervalinteger

The number of "units" to return data for - hours, days, weeks, or months.

1 will return data for the current unit (hour, day, week or month). 2 will return the current and previous units, and so on.

optionalformatstring

The data return format, such as JSON or CSV.

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

Example URL

http://mixpanel.com/api/2.0/events/names?interval=7&expire=1275627103&sig=9f2a0f7024b64
26aa440cf3ecad66165&api_key=f0aa346688cee071cd85d857285a3464&type=general&unit=day

Return format

{'data': {u'pages': {'descriptions': {'2010-03-15': {u'1 weeks later': '2010-03-15',
                                                     u'2 weeks later': '2010-03-15',
                                                     u'3 weeks later': '2010-03-15'},
                                      '2010-03-22': {u'1 weeks later': '2010-03-22',
                                                     u'2 weeks later': '2010-03-22'},
                                      '2010-03-29': {u'1 weeks later': '2010-03-29'}},
                     'series': [u'1 weeks later',
                                u'2 weeks later',
                                u'3 weeks later'],
                     'values': {'2010-03-15': {u'1 weeks later': 0.2102,
                                               u'2 weeks later': 0.1343,
                                               u'3 weeks later': 0.0769},
                                '2010-03-22': {u'1 weeks later': 0.3268,
                                               u'2 weeks later': 0.1675},
                                '2010-03-29': {u'1 weeks later': 0.1813}}}},
 'meta': {'unit': u'week'}}

Event Properties

Method: properties back to top

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

RequiredNameTypeDescription
requiredeventstring

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

requirednamestring

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

optionalvaluesarray

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

requiredtypestring

The analysis type you would like to get data for - such as general, unique, or average events.

Valid values: 'general', 'unique', or 'average'

requiredunitstring

This can be 'hour', 'day', 'week', or 'month'.

It determines the level of granularity of the data you get back.

requiredintervalinteger

The number of "units" to return data for - hours, days, weeks, or months.

1 will return data for the current unit (hour, day, week or month). 2 will return the current and previous units, and so on.

optionalformatstring

The data return format, such as JSON or CSV.

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

optionallimitinteger

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': {'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 back to top

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

Description

Get the top property names for an event.

Parameters

RequiredNameTypeDescription
requiredeventstring

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

requiredtypestring

The analysis type you would like to get data for - such as general, unique, or average events.

Valid values: 'general', 'unique', or 'average'

requiredunitstring

This can be 'hour', 'day', 'week', or 'month'.

It determines the level of granularity of the data you get back.

requiredintervalinteger

The number of "units" to return data for - hours, days, weeks, or months.

1 will return data for the current unit (hour, day, week or month). 2 will return the current and previous units, and so on.

optionallimitinteger

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

Example URL

http://mixpanel.com/api/2.0/events/properties/top?interval=7&expire=1275678109&sig=ce1930
e14e44db542409686a89bf03ef&api_key=f0aa346688cee071cd85d857285a3464&type=general&
event=splash+features&unit=day

Return format

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

Method: values back to top

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

Description

Get the top values for a property.

Parameters

RequiredNameTypeDescription
requiredeventstring

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

requirednamestring

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

requiredtypestring

The analysis type you would like to get data for - such as general, unique, or average events.

Valid values: 'general', 'unique', or 'average'

requiredunitstring

This can be 'hour', 'day', 'week', or 'month'.

It determines the level of granularity of the data you get back.

requiredintervalinteger

The number of "units" to return data for - hours, days, weeks, or months.

1 will return data for the current unit (hour, day, week or month). 2 will return the current and previous units, and so on.

optionallimitinteger

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

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 back to top

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

Description

Get data for a set of funnels over the last N weeks.

Parameters

RequiredNameTypeDescription
requiredfunnelarray

The funnel or funnels that you wish to get data for, encoded as a JSON array.

Example format: '["Signup funnel", "Purchase funnel", "Invite funnel"]'

requiredunitstring

This can only be 'week' for funnels.

It determines the level of granularity of the data you get back.

requiredintervalinteger

The number of weeks to return data for.

1 will return data for the current week. 2 will return the current and previous weeks, and so on.

Example URL

http://mixpanel.com/api/2.0/funnels/?funnel=%5B%22Signup+flow%22%5D&interval=2&expire=
1275687370&sig=0446b1725ffedf241f7bf3d2097af162&api_key=f0aa346688cee071cd85d8
57285a3464&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: names back to top

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

Description

Get the names of the funnels you are tracking.

Parameters

RequiredNameTypeDescription
requiredunitstring

This can only be 'week' for funnels.

It determines the level of granularity of the data you get back.

requiredintervalinteger

The number of weeks to return data for.

1 will return data for the current week. 2 will return the current and previous weeks, and so on.

Example URL

http://mixpanel.com/api/2.0/funnels/names?api_key=f0aa346688cee071cd85d857285a3464&interval=2
&sig=775573914d02cf618de0d545584dfdc9&unit=week&expire=1275687367

Return format

['Signup funnel',
 'Invite funnel',
 'Purchase funnel']

Method: dates back to top

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

Description

Get the dates for which a set of funnels have data.

Parameters

RequiredNameTypeDescription
requiredfunnelarray

The funnel or funnels that you wish to get data for, encoded as a JSON array.

Example format: '["Signup funnel", "Purchase funnel", "Invite funnel"]'

requiredunitstring

This can only be 'week' for funnels.

It determines the level of granularity of the data you get back.

optionallimitinteger

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

Example URL

http://mixpanel.com/api/2.0/funnels/dates?funnel=%5B%22Signup+flow%22%5D&api_key=f0aa
346688cee071cd85d857285a3464&sig=14d36279b876484e087e436420b93bf9&unit=week&
expire=1275687366

Return format

{'Signup funnel': ['2010-05-24',
                   '2010-05-31'],
 'Purchase funnel': ['2010-05-10',
                     '2010-05-17',
                     '2010-05-24',
                     '2010-05-31'] 
}

Funnel Properties

Method: properties back to top

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

Description

Get unique, total, or average data for a funnel property over the last N weeks.

Parameters

RequiredNameTypeDescription
requiredfunnelstring

The single funnel that you wish to get properties data for. Note: this is a string, not an array of funnels.

requirednamestring

The name of the property you want to get data for.

requiredunitstring

This can only be 'week' for funnels.

It determines the level of granularity of the data you get back.

requiredintervalinteger

The number of weeks to return data for.

1 will return data for the current week. 2 will return the current and previous weeks, and so on.

optionallimitinteger

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

Example URL

http://mixpanel.com/api/2.0/funnels/properties/?funnel=Signup+flow&name=referrer&
interval=1&expire=1275689875&sig=d165136d6c94dec5333f1cba04f32fee&api_key=
f0aa346688cee071cd85d857285a3464&unit=week

Return format

{'2010-05-31': {'meta': {'name': 'feature',
                         'steps': 5,
                         'values': ['funnel', 'api']},
                'values': {'api': {'end': 6,
                                   'start': 2,
                                   'steps': {'1': {'count': 2},
                                             '2': {'count': 3},
                                             '3': {'count': 1},
                                             '6': {'count': 1}},
                                   'total_visitors': 7},
                           'funnel': {'end': 6,
                                      'start': 2,
                                      'steps': {'2': {'count': 3},
                                                '3': {'count': 1},
                                                '4': {'count': 1},
                                                '5': {'count': 1},
                                                '6': {'best': True,
                                                      'count': 1}},
                                      'total_visitors': 7}}}}

Method: names back to top

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

Description

Get the top properties for a single funnel.

Parameters

RequiredNameTypeDescription
requiredfunnelstring

The single funnel that you wish to get properties data for. Note: this is a string, not an array of funnels.

requiredunitstring

This can only be 'week' for funnels.

It determines the level of granularity of the data you get back.

requiredintervalinteger

The number of weeks to return data for.

1 will return data for the current week. 2 will return the current and previous weeks, and so on.

optionallimitinteger

The maximum number of property names to return. Defaults to 20.

Example URL

http://mixpanel.com/api/2.0/funnels/properties/names?funnel=Signup+flow&interval=1&expire
=1275690454&sig=c1a00ce402d95600796cb659838c75f7&api_key=f0aa346688cee071cd85d85
7285a3464&unit=week

Return format

{'Signup flow': {'meta': {'date': '2010-05-28 23:00:00'},
                 'names': [{'count': 2,
                            'name': 'authentication',
                            'property': 'authentication'},
                           {'count': 1,
                            'name': 'utm_source',
                            'property': 'utm_source'},
                           {'count': 1132,
                            'name': 'view features',
                            'property': 'view features'},
                           {'count': 1131,
                            'name': 'test_version',
                            'property': 'test_version'}]}}

API Errors

Error format back to top

{'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 back to top

ErrorDescription
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 is not properly JSON encoded.
Invalid endpoint: X You are requesting an endpoint that does not exist.