Skip to main content
GET
/
retention
Query Retention Report
curl --request GET \
  --url https://{regionAndDomain}.com/api/query/retention \
  --header 'Authorization: Basic <encoded-value>'
{
  "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
  }
}
Get cohort analysis. If you specify neither an interval nor a unit, the interval is 1 day. This means that each user gets 24 hours in each interval to do the specified event. An example response with a born_event of ‘event integration’ and event of ‘viewed report’ might look like this: 
{
  "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
  }
}
These results indicate that 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. The Query API has a rate limit of 60 queries per hour and a maximum of 5 concurrent queries.

Authorizations

​
Authorization
string
header
required

Service Account

Query Parameters

​
project_id
integer
required

Required if using service account to authenticate request.

​
workspace_id
integer

The id of the workspace if applicable.

​
from_date
string
required

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

​
to_date
string
required

The date in yyyy-mm-dd format to query to. This date is inclusive.

​
retention_type
enum<string>

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.

Available options:
birth,
compounded
Example:

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

Example:

"Added to cart"

​
event
string

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

Example:

"Viewed report"

​
born_where
string

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

Example:

"properties[\"$os\"]==\"Linux\""

​
where
string

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

Example:

"properties[\"$os\"]==\"Linux\""

​
interval
integer

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.

Example:

1

​
interval_count
integer

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.

Example:

1

​
unit
enum<string>

The interval unit. It can be "day", "week", or "month". Default is "day".

Available options:
day,
week,
month
Example:

"day"

​
unbounded_retention
boolean
default:false

A counting method for retention queries where retention values accumulate from right to left, i.e. day N is equal to users who retained on day N and any day after. The default value of false does not perform this accumulation. Learn more about Counting Method.

Example:

false

​
on
string

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

​
limit
integer

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

Response

200 - application/json

Success.

​
{key}
object