At a glance: The Cohort reporting API provides advertisers a programmatic way to get Cohort data available in the AppsFlyer platform. Use the API to integrate Cohort data into BI, and marketing automation systems.
Example cohort report in the AppsFlyer dashboard
Cohort reporting API
The Cohort reporting API is used to get cohorted campaign performance data from the AppsFlyer platform. It is functionally equivalent to the Cohort dashboard.
Considerations for developers
- Dates: Dates or date ranges refer to lifetime value (LTV) dates, meaning the date the user attributed (converted) and not the date of the activity itself.
- Boolean values: being true or false (case sensitive).
- Data freshness: daily: Make your API call after the daily update time
- Transparent and non-transparent agency traffic: The media source of agency-driven traffic is always the agency and not the original media source. At present the UI version of cohort behaves differently.
- Single app: Cohort API is a single app solution. This is in contrast to Cohort dashboard which supports multiple apps in a single call.
API instructions
The sections contain the information necessary for you to generate and use the Cohort API.
Cohort API facts
Overview | The API call consists of the path, headers, and a JSON containing the data query. Data is returned by default in a CSV file. |
Path |
|
Path parameters (mandatory) |
|
Query parameters (optional) |
Results return as CSV or JSON. The CSV file structure is tabular while that of the JSON record orientated. |
HTTP method | POST |
Accepted content types | application/json |
Authorization |
|
Date limitations |
|
Rate limitation |
|
Boolean values | Always in lower case: true, false |
Key |
Value | Mandatory |
---|---|---|
Content-Type | application/json |
Yes |
Authorization | Bearer api_token_placeholder |
Yes |
Accept | application/json |
Yes |
Filtering and grouping parameters
Use filter parameters to get the necessary data.
Parameter name |
Description | Mandatory |
---|---|---|
cohort _type |
Cohort attribution (conversion) type is one of the following:
|
Yes |
min_cohort_size |
Minimum cohort size is used to reduce the number of records returned by excluding cohorts having few users. This means that the users KPI has a value equal or greater to that specified.
|
No |
from |
Lower bound of the LTV attribution date range.
|
Yes |
to |
Higher bound of the LTV attribution date range
|
Yes |
partial_data |
To avoid data distortion and misinterpretation Cohort returns data of complete days. However, the data of partial days can be useful. The number of complete cohort days for a query is calculated as the difference between today's date and the to date.
Example: On May 10, the number of complete cohort days for users converting during April 1-30, is 10.
|
No |
filters |
Filter the data and period days returned. Select filters from the filter dimensions list.
|
No |
Use groupings to include additional columns and make your reports less granular.
Parameter |
Values | Mandatory |
---|---|---|
groupings |
|
Yes |
Selecting and formatting KPIs
- The table lists the KPIs available and their associated functions. When you call a KPI, all its functions return.
- The following KPIs always return: users, ecpi, and cost
- Select one additional KPI per call.
Functions | ||||||
---|---|---|---|---|---|---|
Default/ Optional | KPI (Dimensions name) | Count | cvr (conversion rate) | Rate | Sum | Unique users |
Number | Percentage | Percentage | Number | Number | ||
Always | users | ✓ | - | - | - | - |
Always | ecpi | - | - | ✓ | - | - |
Always | cost | - | - | - | ✓ | - |
Optional | "event_name" |
✓ | - | ✓ | ✓ | |
Optional | revenue | ✓ | - | - | ✓ | - |
Optional | ROAS | - | - | ✓ | - | - |
Optional | roi | - | - | ✓ | - | - |
Optional | sessions | ✓ | - | ✓ | - | ✓(1) |
Optional | uninstalls | ✓ | - | ✓ | - | - |
(1) Unique sessions returns when aggregation_type=on_day |
Parameter |
Values | Mandatory parameter |
---|---|---|
kpis |
Select one KPI from the KPIs available. In the future, we plan to allow the selection of multiple KPIs.
|
Yes |
KPI format parameters set the format of the KPIs returned.
Parameter |
Values | Mandatory |
---|---|---|
preferred_currency |
KPI revenue currency
|
No |
preferred_timezone |
Time zone of data ranges
|
No |
aggregation_type |
|
Yes |
per_user |
Divide the KPI function by the number of app users. Applies only to relevant KPIs.
|
No |
List of group by and filter by dimensions
Dimension name |
Dimension API value |
Groupings |
Filters |
---|---|---|---|
Ad |
af_ad |
✓ |
✓ |
Ad ID |
af_ad_id |
✓ |
✓ |
Campaign |
c |
✓ |
✓ |
Campaign ID |
af_c_id |
✓ |
✓ |
Channel |
af_channel |
✓ |
✓ |
Media Source |
pid |
✓ |
✓ |
Sub Param 1 |
af_sub1 |
✓ |
✓ |
Keywords |
af_keywords |
✓ |
✓ |
Agency |
af_prt |
✓ |
✓ |
Conversion Type |
conversion_type |
✓ |
✓ |
Site ID |
site_id |
✓ |
✓ |
Revenue Type |
revenue_type |
x |
✓ |
Attributed Touch Type |
attributed_touch_type |
✓ |
✓ |
Adset |
af_adset |
✓ |
✓ |
Adset ID |
af_adset_id |
✓ |
✓ |
Country |
geo |
✓ |
✓ |
Date (install/re-attribution/re-engagement date in the context of the cohort_type selected) |
date |
✓ |
x |
Period |
period
|
x |
✓ |
Curl example
This example contains a complete API call.
Curl -L -X POST 'https://hq1.appsflyer.com/api/cohorts/v1/data/app/<insert your app_id here>?format=<insert results format here>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <cohort_api_token_placeholder. Note the token has more than 700 characters.>' \
-H 'Accept: application/json' \
--data-raw '{
"cohort_type": "user_acquisition",
"min_cohort_size": 1,
"preferred_timezone": false,
"from": "2020-01-01",
"to": "2020-01-31",
"filters": {
"period": [
0,
1,
2,
10,
30,
60
],
"geo": [
"US",
"CN"
],
"pid": [
"Facebook Ads",
"gooleadwords_int"
]
},
"preferred_currency": true,
"aggregation_type": "on_day",
"per_user": false,
"groupings": [
"pid",
"date"
],
"kpis": [
"sessions"
]
}'
Example files returned: CSV, JSONPython example
import http.client
import mimetypes
conn = http.client.HTTPSConnection("hq1.appsflyer.com")
payload = "{\r\n \"cohort_type\": \"user_acquisition\",\r\n \"min_cohort_size\": 1,\r\n \"preferred_timezone\": false,\r\n \"from\": \"2020-05-01\",\r\n \"to\": \"2020-05-10\",\r\n \"preferred_currency\": true,\r\n \"aggregation_type\": \"cumulative\",\r\n \"per_user\": false, \r\n \"groupings\": [\r\n \"pid\",\r\n \"date\"\r\n ],\r\n \"kpis\": [\r\n \"roas\"\r\n ]\r\n}"
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer [Enter token here]',
'Accept': 'application/json',
'Content-Type': 'application/json'
}
conn.request("POST", "/api/cohorts/v1/data/app/[My App ID here]?format=csv", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Additional information
Response codes and troubleshooting
Response code |
Message |
Remark |
---|---|---|
200 | OK |
Valid data returned |
200 | OK |
|
401 | Unauthorized |
|
404 | Not found |
|
422 | Unprocessable entity |
Common reasons for this error code are:
|
CSV file name structure
The name allocated to a CSV file that returns is generated from the API query. The structure is as detailed in the table that follows.
Example CSV file name
cohort_aggregation_type_per_user_kpi_report_app_id_from_to_timezone_currency_hash.csv
Variable | Possible values |
---|---|
aggregation_type |
|
per_user |
|
kpi | Example: sessions |
app_id | The app id requested |
from | from date: format yyyy-mm-dd |
to | to date: format yyyy-mm-dd |
timezone | Time zone default UTC |
currency | Currency code default USD |
hash |
Alphanumeric hash string length=5 |
Using period filters
Period refers to the day post-attribution, where period 0 is the attribution day. For example, a user installs the app on January 1. This is the attribution day. A purchase made on period 0 means it was made on January 1. A purchase made on period 3 means it was made on January 4. Similarly, a user who installs on January 11, this is period 0. A purchase made on January 14 would be period 3.
If your report date range is January 1 to January 11 users who attributed (installed) during this period are included in the report. No other data is included.
- The value of the period can be one or more of the following 0-90 and 180. For example, 0, 1, 2, 30, 180.
- if no period specified, the default values are: 0, 1, 2, and so on to 30, 60, 90, and 180.
Example period filter
- This example contains the JSON query parameters, raw data, and resulting CSV file.
- The query filters period of 0, 1, and 2 and the KPI selected is revenue.
- As a result, the data returned contains:
- The measures of users, cost, and ecpi which always return
- Revenue measures consisting of sum and count for each period meaning periods 0, 1, and 2.
Query
{
"cohort_type": "user_acquisition",
"min_cohort_size": 1,
"preferred_timezone": false,
"from": "2019-12-01",
"to": "2020-01-01",
"filters": {
"period": [
0,
1,
2
]
},
"aggregation_type": "on_day",
"per_user": false,
"groupings": [
"pid"
],
"kpis": [
"revenue"
]
}
Raw data
Results
User interface mapping to API parameters
The figures that follow map the Cohort analytics user interface to the API parameters. The two solutions - API and user interface are similar but not identical.
The API version has the following additional options:
- Currency selection
- Timezone selection
- Filtering by period


Difference between aggregation types
Traits and limitations
Trait | Remarks |
---|---|
Ad network access | No |
Agency access | No |
Agency transparency | Not supported |
App-specific time zone | Yes |
App-specific currency | Yes |
Size limitations | None |
Rate limitation |
API call-rate limit: 60 calls per minute per account |
Organic data | Available |
Non-organic data | Available |
Cost data limitation |
AppsFlyer does not report cost data for keywords that contain uppercase letters in the cohort report or cohort API. |
Data freshness | Realtime. Cost and uninstall metrics update daily |
Historical data | Earliest conversion data (install or retarget) supported: January 1, 2019 |
Team member access | The authorization token is available to the account admin in the dashboard. |