Visit the Dev Docs
A better version of this page exists at https://developer.mixpanel.com/docs/data-export-api.The Mixpanel Formatted Data Export API, or the Query API, runs queries and returns the corresponding results.
The Query API can also be used to query and export user information, such as user profile properties and a user's activity feed.
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.
These are official libraries that can be used to easily consume data through the Mixpanel API.
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/ \
#Replace API_SECRET with your project's API secret
-u 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
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
- All requests must have the following parameters:
api_key,expire,sig. api_keycan be found on your account page under API Information.expireis 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.- 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 theapi_secretby 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)
- Lastly, include
sigwith 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
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/
from_date
stringrequired
The beginning of the date range to get annotations for in yyyy-mm-dd format. This date is inclusive.
to_date
stringrequired
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
stringrequired
The time in yyyy-mm-hh HH:mm:SS when you want to create the annotation at.
description
stringrequired
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
id
stringrequired
The ID of the annotation you wish to update.
date
stringrequired
The time in yyyy-mm-hh HH:mm:SS to update the annotation to.
description
stringrequired
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}
id
stringrequired
The ID of the annotation to delete.
https://mixpanel.com/api/2.0/annotations/delete?id=42
{"error": false}
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/
event
arrayrequired
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
stringrequired
The analysis type you would like to get data for - such as general, unique, or average events. Valid values: "general", "unique", or "average".
unit
stringrequired
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
integeroptional
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
integeroptional
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
stringoptional
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
stringoptional
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/
type
stringrequired
The analysis type you would like to get data for - such as general, unique, or average events. Valid values: "general", "unique", or "average".
limit
integeroptional
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/
type
stringrequired
The analysis type you would like to get data for - such as general, unique, or average events. Valid values: "general", "unique", or "average".
limit
integeroptional
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"]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/
event
stringrequired
The event that you wish to get data for. Note: this is a single event name, not an array.
name
stringrequired
The name of the property you would like to get data for.
values
arrayoptional
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
stringrequired
The analysis type you would like to get data for - such as general, unique, or average events. Valid values: "general", "unique", or "average"
unit
stringrequired
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
integeroptional
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
stringoptional
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
stringoptional
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
stringoptional
The data return format, such as JSON or CSV. Options: "json" (default), "csv".
limit
integeroptional
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/
event
stringrequired
The event that you wish to get data for. Note: this is a single event name, not an array.
limit
integeroptional
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/
event
stringrequired
The event that you wish to get data for. Note: this is a single event name, not an array.
name
stringrequired
The name of the property you would like to get data for.
limit
integeroptional
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"]The following methods return Mixpanel funnel data.
funnels
Get data for a funnel.
URI: https://mixpanel.com/api/2.0/funnels/
funnel_id
integerrequired
The funnel that you wish to get data for.
from_date
stringoptional
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
stringoptional
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
integeroptional
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
stringoptional
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
integeroptional
The number of days you want each bucket to contain. The default value is 1.
unit
stringoptional
This is an alternate way of specifying interval and can be "day", "week", or "month".
on
stringoptional
The property expression to segment the event on. See the expression section below.
limit
integeroptional
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}}
}}https://mixpanel.com/api/2.0/funnels/list
[{"funnel_id": 7509, "name": "Signup funnel"},
{"funnel_id": 9070, "name": "Funnel tutorial"}]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/
event
stringrequired
The event that you wish to segment on.
from_date
stringrequired
The date in yyyy-mm-dd format from which to begin querying for the event from. This date is inclusive.
to_date
stringrequired
The date in yyyy-mm-dd format from which to stop querying for the event from. This date is inclusive.
on
stringoptional
The property expression to segment the event on. See the expressions section below.
unit
stringoptional
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
integeroptional
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.
limit
integeroptional
Return the top property values. Defaults to 60. Maximum value 10,000. This parameter does nothing if "on" is not specified.
type
stringoptional
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".
format
stringoptional
Can be set to "csv".
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/
event
stringrequired
The event that you wish to segment on.
from_date
stringrequired
The date in yyyy-mm-dd format from which to begin querying for the event from. This date is inclusive.
to_date
stringrequired
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
stringrequired
The property expression to segment the event on. This expression must be a numeric property. See the expressions section below.
unit
stringoptional
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".
type
optionalstring
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/
event
stringrequired
The event that you wish to segment on.
from_date
stringrequired
The date in yyyy-mm-dd format from which to begin querying for the event from. This date is inclusive.
to_date
stringrequired
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
stringrequired
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
stringoptional
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".
curl https://mixpanel.com/api/2.0/segmentation/sum?
-u 6a6a06a41d496653286a86ed6886f216:
-d event="Item Sold"
-d on='(properties["Item Price"])'{"status": "ok",
"computed_at": "2019-10-07T23:02:11.666218+00:00",
"results": {"2019-10-07": 4,
"2019-10-06": 7}
}
average
Averages an expression for events per unit time.
URI: https://mixpanel.com/api/2.0/segmentation/average/
event
stringrequired
The event that you wish to segment on.
from_date
stringrequired
The date in yyyy-mm-dd format from which to begin querying for the event from. This date is inclusive.
to_date
stringrequired
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
stringrequired
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
stringoptional
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
stringoptional
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"}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
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.
from_date
stringrequired
The date in yyyy-mm-dd format from which to begin generating cohorts from. This date is inclusive.
to_date
stringrequired
The date in yyyy-mm-dd format from which to stop generating cohorts from. This date is inclusive.
retention_type
stringoptional
Must be either "birth" or "compounded". Defaults to "birth". The “birth” retention type corresponds to first time retention. The “compounded” retention type corresponds to recurring retention. See the Types of Retention article for more information.
born_event
stringoptional
The first event a user must do to be counted in a birth retention cohort. Required when retention_type is "birth"; ignored otherwise.
event
stringoptional
The event to generate returning counts for. Applies to both birth and compounded retention. If not specified, we look across all events.
born_where
stringoptional
An expression to filter born_events by. See the expressions section above.
interval
integeroptional
The number of units (can be specified in either days, weeks, or months) that you want per individual bucketed interval. May not be greater than 90 days if days is the specified unit. The default value is 1.
interval_count
integeroptional
The number of individual buckets, or intervals, that are returned; defaults to 1. Note that we include a "0th" interval for events that take place less than one interval after the initial event.
unit
stringoptional
The interval unit. It can be "day", "week", or "month". Default is "day".
on
stringoptional
The property expression to segment the second event on. See the expressions section above.
limit
integeroptional
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 users 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 users who did event ("viewed report") on the specified date. 9 of those users 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 users 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 users are performing events.
URI: https://mixpanel.com/api/2.0/retention/addiction/
from_date
stringrequired
The date in yyyy-mm-dd format from which to begin generating cohorts from. This date is inclusive.
to_date
stringrequired
The date in yyyy-mm-dd format from which to stop generating cohorts from. This date is inclusive.
unit
stringrequired
The overall time period to return frequency of actions for. Can be "day", "week", or "month".
addiction_unit
stringrequired
The granularity to return frequency of actions at. Can be "hour" or "day".
event
stringoptional
The event to generate returning counts for.
where
stringoptional
An expression to filter the returning events by. See the expressions section above.
on
stringoptional
The property expression to segment the second event on. See the expressions section above.
limit
integeroptional
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 users did the event ("Viewed report") during at least 1 hour out of the next 24 hour period (the period specified by "unit"). 204 users did the event during at least 2 hours. 117 users did the event during at least 3 hours.
distinct_id
stringoptional
A unique identifier used to distinguish an individual profile.
distinct_ids
array of stringsoptional
The list of distinct_ids to return profile information on.
output_properties
array of stringsoptional
A JSON array of names of properties you want returned.
Example: output_properties=["$last_name", "$email", "Total Spent"]
This parameter can drastically reduce the amount of data returned by the API when you're not interested in all properties and can speed up queries significantly.
session_id
stringoptional
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
integeroptional
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
integeroptional
If you are exporting user profiles using an event selector, you use a behaviors parameter in your request. behaviors and filter_by_cohort are mutually exclusive.
as_of_timestamp
integeroptional
This parameter is only useful when also using behaviors.
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
filter_by_cohort
stringoptional
Takes a JSON object with a single key called id whose value is the cohort ID. behaviors and filter_by_cohort are mutually exclusive.
Example: filter_by_cohort='{"id":12345}'
include_all_users
booleanoptional
include_all_users=True means that the Engage API will include distinct_ids that don’t have a user profile. This is the default.
include_all_users=False means that the Engage API will only include distinct_ids with user profiles.
*this parameter is only applied when combined with filter_by_cohort
curl https://mixpanel.com/api/2.0/engage/ \
-u API_SECRET: \
-d where "(properties["$email"] == "example@mixpanel.com")" \
# Using one distinct_id
-d distinct_id="4"
# Using multiple distinct_ids
# -d 'distinct_ids=["4","5","6"]'{"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)project_id
stringrequired
The id of the project containing the revenue data.
from_date
stringrequired
The date in yyyy-mm-dd format from which to begin generating cohorts from. This date is inclusive.
to_date
stringrequired
The date in yyyy-mm-dd format from which to stop generating cohorts from. This date is inclusive.
unit
integeroptional
The overall time period to return frequency of actions for. Can be "day", "week", or "month".
https://mixpanel.com/api/2.0/engage/revenue/?project_id=1888932&from_date=2017-11-01&to_date=2018-11-12&unit=month
{
"results":{
"$overall":{
"amount":59.98,
"count":2701666,
"paid_count":1
},
"2017-11-01":{
"amount":0.00,
"count":2605741,
"paid_count":0
},
"2017-12-01":{
"amount":59.98,
"count":2612155,
"paid_count":1
}
},
"session_id":"1547668188354-012d4cd041b9db7d39f3f54d1d06425c",
"status":"ok"
}{"error": "Invalid parameter: unit",
"request": "/api/2.0/events/general?interval=7&event=%5B%22splash+features%22%5D&unit=day"}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.
Comments
Please sign in to leave a comment.