Query Retention Report
Query retention (cohort analysis) data for users who did a born event and then a return event, with interval and unit options
curl --request GET \
--url https://{regionAndDomain}.com/api/query/retention \
--header 'Authorization: Basic <encoded-value>'import requests
url = "https://{regionAndDomain}.com/api/query/retention"
headers = {"Authorization": "Basic <encoded-value>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Basic <encoded-value>'}};
fetch('https://{regionAndDomain}.com/api/query/retention', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{regionAndDomain}.com/api/query/retention",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Basic <encoded-value>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://{regionAndDomain}.com/api/query/retention"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Basic <encoded-value>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://{regionAndDomain}.com/api/query/retention")
.header("Authorization", "Basic <encoded-value>")
.asString();require 'uri'
require 'net/http'
url = URI("https://{regionAndDomain}.com/api/query/retention")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Basic <encoded-value>'
response = http.request(request)
puts response.read_body{
"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
}
}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
}
}
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.Query Parameters
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.
birth, compounded "birth"
An expression to filter born_events by. See the expressions section above.
"properties[\"$os\"]==\"Linux\""
An expression to filter born_events by. See the expressions section above.
"properties[\"$os\"]==\"Linux\""
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.
false
The property expression to segment the second event on. See the expressions section above.
Was this page helpful?
curl --request GET \
--url https://{regionAndDomain}.com/api/query/retention \
--header 'Authorization: Basic <encoded-value>'import requests
url = "https://{regionAndDomain}.com/api/query/retention"
headers = {"Authorization": "Basic <encoded-value>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Basic <encoded-value>'}};
fetch('https://{regionAndDomain}.com/api/query/retention', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{regionAndDomain}.com/api/query/retention",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Basic <encoded-value>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://{regionAndDomain}.com/api/query/retention"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Basic <encoded-value>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://{regionAndDomain}.com/api/query/retention")
.header("Authorization", "Basic <encoded-value>")
.asString();require 'uri'
require 'net/http'
url = URI("https://{regionAndDomain}.com/api/query/retention")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Basic <encoded-value>'
response = http.request(request)
puts response.read_body{
"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
}
}