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
- general
get total visitor interactions with an event over a time period - unique
get unique visitor interactions with an event over a time period - average
get average visitor interactions with an event over a time period - retention
get visitor retention data for an event - top_events
get stats for today's events
Properties
- general
get total visitor interactions with a property over a time period - unique
get unique visitor interactions with a property over a time period - average
get average visitor interactions with a property over a time period - general_top
get the most common properties for an event
Funnels
- names:
get the names of all funnels tracked - unique:
get unique funnel data for the current week - top_property_names:
get the properties of a funnel - unique_properties:
get the values of a funnel property
Geolocation
- unique
get unique visitor geolocation data over a time period
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
Visit the Ruby respository
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_keycan 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. - args = all query parameters going to be sent out with the request (e.g.
api_key, unit, interval, expire, 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/events/1.0/general?format=json&interval=24&expire=1248393099&sig=69a72174b36e35185b8b6c11241ba001&api_key=ed0b8ff6cc3dbb37a521b50129915a18&event=%5B%22pages%22%5D&unit=hour
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 codeEvents
Method: general back to top
URI: http://mixpanel.com/api/events/1.0/general/
Description
Get a log of all visitor interactions with an event or events for the last N hours, days, weeks or months.
Parameters
| Required | Name | Type | Description |
| required | event | string |
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 | unit | string | This can be "hour", "day", "week", or "month". It determines the level of granularity of the data you get back. |
| required | interval | integer | 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. |
Method: unique back to top
URI: http://mixpanel.com/api/events/1.0/unique/
Description
Get a log of all unique visitor interactions with an event or events for the last N days, weeks or months.
Parameters
| Required | Name | Type | Description |
| required | event | string |
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 | unit | string | This can be "day", "week", or "month". It determines the level of granularity of the data you get back. |
| required | interval | integer | The number of "units" to return data for - days, weeks, or months. 1 will return data for the current unit (day, week or month). 2 will return the current and previous units, and so on. |
Method: average back to top
URI: http://mixpanel.com/api/events/1.0/average/
Description
Get a log of the average interactions per visitor (total divided by unique interactions) for an event or events over the last N days, weeks or months.
Parameters
| Required | Name | Type | Description |
| required | event | string |
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 | unit | string | This can be "day", "week", or "month". It determines the level of granularity of the data you get back. |
| required | interval | integer | The number of "units" to return data for - days, weeks, or months. 1 will return data for the current unit (day, week or month). 2 will return the current and previous units, and so on. |
Method: retention back to top
URI: http://mixpanel.com/api/events/1.0/retention/
Description
Get a log of visitor retention data for an event or events over the last 7 days, weeks or months.
Parameters
| Required | Name | Type | Description |
| required | event | string |
The event that you wish to get data for. Visitor retention data can only be requested for a single event.
Example format: event=your+event |
| required | unit | string | This can be "day", "week", or "month". This determines whether you see visitor retention over 7 days, 7 weeks, or 7 months. |
| required | interval | integer | The number of "units" to return data for - days, weeks, or months. The maximum interval for visitor retention is 7. |
Method: top_events back to top
URI: http://mixpanel.com/api/events/1.0/top_events/
Description
Get the current tally and relative difference from yesterday for all events that have happened today.
Parameters
| Only authorization parameters are required for this method. |
Properties
Method: general back to top
URI: http://mixpanel.com/api/properties/1.0/general/
Description
Get a log of total visitor interaction with a property of an event over the last N days, weeks or months.
Parameters
| Required | Name | Type | Description |
| required | name | string | The property name. |
| required | event | string |
The event that "name" is a property of.
Example format: event=your+event |
| required | unit | string | This can be "hour", "day", "week", or "month". It determines the level of granularity of the data you get back. |
| required | interval | integer | 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. |
Method: unique back to top
URI: http://mixpanel.com/api/properties/1.0/unique/
Description
Get a log of unique visitor interaction with a property of an event over the last N days, weeks or months.
Parameters
| Required | Name | Type | Description |
| required | name | string | The property name. |
| required | event | string |
The event that "name" is a property of.
Example format: event=your+event |
| required | unit | string | This can be "day", "week", or "month". It determines the level of granularity of the data you get back. |
| required | interval | integer | The number of "units" to return data for - days, weeks, or months. 1 will return data for the current unit (day, week or month). 2 will return the current and previous units, and so on. |
Method: average back to top
URI: http://mixpanel.com/api/properties/1.0/average/
Description
Get a log of average visitor interaction (total divided by unique interactions) with a property of an event over the last N days, weeks or months.
Parameters
| Required | Name | Type | Description |
| required | name | string | The property name. |
| required | event | string |
The event that "name" is a property of.
Example format: event=your+event |
| required | unit | string | This can be "day", "week", or "month". It determines the level of granularity of the data you get back. |
| required | interval | integer | The number of "units" to return data for - days, weeks, or months. 1 will return data for the current unit (day, week or month). 2 will return the current and previous units, and so on. |
Method: general_top back to top
URI: http://mixpanel.com/api/properties/1.0/general_top/
Description
Get a list of the top properties for an event.
Parameters
| Required | Name | Type | Description |
| required | event | string | The event to get properties for. Only 1 event can be passed to this function. |
| required | unit | string | This can be "day", "week", or "month". It determines the level of granularity of the data you get back. |
| required | interval | integer | The number of "units" to return data for - days, weeks, or months. 1 will return data for the current unit (day, week or month). 2 will return the current and previous units, and so on. |
Funnels
Method: names back to top
URI: http://mixpanel.com/api/funnel/1.0/names/
Description
Get a list of funnels tracked on this project.
Parameters
| Required | Name | Type | Description |
| required | unit | string | This can be "day", "week", or "month". It determines how old the funnels returned are. |
| required | interval | integer | The number of "units" to return data for - days, weeks, or months. 1 will return data for the current unit (day, week or month). 2 will return the current and previous units, and so on. A monday must be included in the range to recieve data back. |
Method: unique back to top
URI: http://mixpanel.com/api/funnel/1.0/unique/
Description
Get a week of funnel data with counts for each step.
Parameters
| Required | Name | Type | Description |
| required | funnel | string | The name of the funnel. |
| required | unit | string | Currently, the funnel only supports "week" |
| required | interval | integer | Currently, the funnel only supports 1 week. |
Method: top_property_names back to top
URI: http://mixpanel.com/api/funnel/1.0/top_property_names/
Description
Get a list of the top property names for a funnel.
Parameters
| Required | Name | Type | Description |
| required | funnel | string | The name of the funnel. |
| required | unit | string | Currently, the funnel only supports "week" |
| required | interval | integer | Currently, the funnel only supports 1 week. |
Method: unique_properties back to top
URI: http://mixpanel.com/api/funnel/1.0/unique_properties/
Description
Get a list of values for a property at each step in a funnel.
Parameters
| Required | Name | Type | Description |
| required | funnel | string | The name of the funnel. |
| required | name | string | The name of the funnel property. |
| required | unit | string | Currently, the funnel only supports "week" |
| required | interval | integer | Currently, the funnel only supports 1 week. |
Geolocation
Method: unique back to top
URI: http://mixpanel.com/api/maps/1.0/unique/
Description
Get a log of unique visitor interactions with an event over N days, weeks or months, grouped by country.
Parameters
| Required | Name | Type | Description |
| required | event | string | The name of the event. |
| required | unit | string | This can be "day", "week", or "month". It determines the level of granularity of the data you get back. |
| required | interval | integer | The number of "units" to return data for - days, weeks, or months. 1 will return data for the current unit (day, week or month). 2 will return the current and previous units, and so on. |
API Errors
Error format back to top
Errors are returned as a JSON string with the following format:
'{
"request": "The request you sent",
"error": ["Array", "of", "errors"]
}'
Here is an example error:
'{
"request": "/api/events/1.0/general?eventl=%5B%22pages%22%5D&format=json&interval=4
&expire=1256713091&sig=9dc3c17383626650dbc04eee801d67b8
&api_key=f0aa346688cee071cd85d857285a3464&unit=day",
"error": ["Missing required parameter: event"]
}'
Error table back to top
| Error | Description |
| Invalid API endpoint | You tried to access an endpoint other than events, properties, maps, or funnel |
| Invalid API endpoint method | The method you tried to access (such as general, unique, etc) was invalid for this service |
| 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. |