Cohort reporting API (beta)

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

CohortAPIIntro.jpg

Cohort reporting API 

The Cohort reporting API is used to get cohorted campaign performance data from the AppsFlyer platform. It is functionally equivalent to Cohort analytics available in the 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.
  • Data freshnessdaily: 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. The Cohort UI version in the platform behaves similarly.

API instructions

The sections contain the information necessary for you to generate and use the Cohort API. 

Find.png  Dear Developer!  We know that many times API guides are frustrating to use. We hope that you found this guide friendly. Give us feedback, scroll down to the end of the guide to do so. 

Cohort API facts

Overview The API call consist of the path, headers, and a JSON containing the data query. Data is returned by default in a CSV file.
Path

https://hq1.appsflyer.com/api/cohorts/v1/data/app/app_id

Path parameters  (mandatory)
  • app_id: Is the app identifier as found in the AppsFlyer dashboard. Insert it exactly as it appears in the dashboard.
  • Ensure that iOS apps are prefixed with id

Query parameters

(optional)

Results return as CSV or JSON. The CSV file structure is tabular while that of the JSON record orientated.

  • [Default] csv the file name is dependant on the query.
  • json containing a query and results section
  • Example: format=json
  • https://hq1.appsflyer.com/api/cohorts/v1/data/app/app_id?format=json
HTTP method POST
Accepted content types application/json
Authorization
  • Bearer token in the request header
  • Reach out to your CSM to enable Cohort API and then Get the token in the dashboard
    • The same token is used for all apps in the account
Date limitations
  • Earliest date supported (conversion) January 1, 2019
  • Maximum query range: 32 days
Rate limitation
  • API call-rate limited to 60 calls per minute per account  
  • Queries return up to 10,000 rows
Cohort API facts

Request headers

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. 

Filtering parameters

Parameter name

Description Mandatory 

cohort _type

Cohort attribution (conversion) type is one of the following: user_acquisitionretargetingunified

  • Unified combines the performance of user acquisition and retargeting campaigns.
  • If an event is attributed to both retargeting and user acquisition campaigns, only the retargeting event is included in KPIs returned, meaning is_primary=true
  • Format: String
  • Example: "cohort_type": "user_acquisition"
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. 

  • Format: Integer
  • Default: 1 
  • Example: "min_cohort_size": 50
No

from 

Lower bound of the LTV attribution date range.

  • Format: String yyyy-mm-dd
  • Example: "from": "2020-01-02"
Yes
to

Higher bound of the LTV attribution date range

  • Number of the days in the range: 1-31 days
  • For a single day: from and to values are identical. 
  • Format: yyyy-mm-dd
  • Example: "from": "2020-01-01", "to": 2020-01-31 is 31 days.
Yes

filters

Filter the data and period days returned. Select filters from the filter dimensions list.

  • Format: Strings in a nested JSON
  • Example limit to specific Geos: "filters": {"geo": "US"} includes only users attributed to the United States. 
  • Example period (cohort) days: The period filter sets the days for which measures are returned. The possible values are: 0-90 and 180.
  • Default:  If no period filter is set the days 0-30, 60, 90, and 180 return. Example filter with period
 No

Use groupings to include additional columns and make your reports less granular.

Grouping parameters

Parameter

Values Mandatory 

groupings

  • Select 1-4 groupings from the grouping dimensions list.
  • Format: Strings in an array
  • Example: "groupings": ["af_ad", "c", "af_c_id", "af_prt"]
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.
Available KPIs and associated functions
    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 roi - - - -
Optional Sessions - -
Optional uninstalls - - -

Parameter

Values Mandatory parameter

kpis

Select one KPI from the KPIs available. In the future, we plan to allow the selection of multiple KPIs.

  • For each KPI requested, all functions are returned. 
  • Format: Strings in an array 
  • Example A: "kpis": ["sessions"]
  • Example B: "kpis": ["event_name"]
Yes

KPI format parameters set the format of the KPIs returned. 

Presentation of KPI functions

Parameter

Values Mandatory 

preferred_currency

KPI revenue currency

  • If true, revenue is returned using the app-specific currency set in the platform. 
  • [Default] If false, results return in USD.
  • Format: Boolean 
  • Platform UI version: True

 No

preferred_timezone

Time zone of data ranges

  • If true, times are expressed using the app-specific time zone set in the platform.
  • [Default] If false, times are expressed using UTC time zone.
  • Format: Boolean 
  • Platform UI version: True

 No

aggregation_type

  • cumulative
  • on_day

"aggregation_type": "cumulative"

Format: String

Yes

per_user

Divide the KPI function by the number of app users. Applies only to relevant KPIs.

  • If true, KPI values are divided by the number of users in the cohort.
  • If false, KPI values are not divided by the number of users.
  • Format: Boolean 
  • Example if true: total revenue is $1000, the number of app users is 500, the value returned is $2. 
 No

List of group by and filter by dimensions

Available grouping and filter 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

Attributed Touch Type

attributed_touch_type

Adset

af_adset

Adset ID

af_adset_id

 

Country

geo

Date (event date) 

date

Period

period 

Detailed explanation

 

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 <api_token_placeholder>' \
-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: CSVJSON

Python example

PythonNode JS
import requests

url = "https://hq1.appsflyer.com/api/cohorts/v1/data/app/[insert your app_id here]?format=[insert results format here]"

payload = "--data-raw '{\n    \"cohort_type\": \"user_acquisition\",\n    \"min_cohort_size\": 1,\n    \"preferred_timezone\": false,\n    \"from\": \"2020-01-01\",\n    \"to\": \"2020-01-31\",\n    \"filters\": {\n        \"period\": [\n            0,\n            1,\n            2,\n            10,\n            30,\n            60\n        ],\n        \"geo\": [\n            \"US\",\n            \"CN\"\n        ],\n        \"pid\": [\n            \"Facebook Ads\",\n            \"gooleadwords_int\"\n        ]\n    },\n    \"preferred_currency\": true,\n    \"aggregation_type\": \"on_day\",\n    \"per_user\": false,    \n    \"groupings\": [\n        \"pid\",\n        \"date\"\n    ],\n    \"kpis\": [\n        \"sessions\"\n    ]\n}'"
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer [api_token_placeholder]',
  'Accept': 'application/json'
}

response = requests.request("POST", url, headers=headers, data = payload)

print(response.text.encode('utf8'))
   

Additional information

Response codes and troubleshooting

Response codes

Response code 

Message

Remark 

200 OK

Valid data returned

200 Empty  The query was valid but no data was found matching the query. 
401 Unauthorized The authorization token is not legal
404 Not found
  • Eliminate any network, firewall, etc.  related problems. 
  • Ensure that the App ID specified in the endpoint is authorized for Cohort API
  Unprocessable entity Error message details are contained in the response body

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
CSV file name structure depends on the API query
Variable Possible values
aggregation_type
  • on_day
  • cumulative
per_user
  • per_user 
  • False: Null 
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

mceclip1.png

Results

mceclip0.png

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

CohortMapping.jpg

Cohortmapping2.jpg

Difference between aggregation types

CohortRevnueCumulative.jpg

Traits and limitations

Trait
Trait Yes  / No x Remarks 
Ad network access  x  
Agency access x  
Agency transparency x The media source of agency-driven traffic is always the agency and not the original media source. The Cohort UI version in the platform behaves similarly. 
App-specific time zone  
App-specific currency   
Size limitations None  
Throttling

 API call-rate limited to 60 calls per minute per account  

Organic data Available
Non-organic data Available
Data freshness  Daily  
Historical data Earliest conversion data (install or retarget) supported: January 1, 2019
Team member access x The authorization token is available to the account admin in the dashboard.

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

CohortAPIIntro.jpg

Cohort reporting API 

The Cohort reporting API is used to get cohorted campaign performance data from the AppsFlyer platform. It is functionally equivalent to Cohort analytics available in the 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.
  • Data freshnessdaily: 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. The Cohort UI version in the platform behaves similarly.

API instructions

The sections that follow, starting with a complete example, contain the information necessary for you to generate and use the Cohort API. 

Cohort API facts

API endpoint

https://hq1.appsflyer.com/api/cohorts/v1/data/app/app_id

  • app_id: Is the app identifier as found in the AppsFlyer dashboard. Insert it exactly as it appears in the dashboard.
  • Ensure that iOS apps are prefixed with id
HTTP method POST
Accepted content types application/json
Authorization
  • Bearer token in the request header
  • Reach out to your CSM to enable Cohort API and then Get the token in the dashboard
    • The same token is used for all apps in the account
Date limitation
  • Earliest date supported January 1, 2019
  • Maximum query range: 32 days
Rate limitation
  • API call-rate limited to 60 calls per minute per account  
  • API call responses return up to 10,000 rows
Cohort API facts

Parameter

Description Mandatory
format

Results return as CSV or JSON. The CSV file structure is tabular while that of the JSON record orientated.

  • [Default] csv the file name is dependant on the query.
  • json containing a query and results section
  • Example: format=json
No
Endpoint parameters

Request headers

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. 

Filtering parameters

Parameter name

Description Mandatory 

cohort _type

Cohort attribution (conversion) type is one of the following: user_acquisitionretargetingunified

  • Unified combines the performance of user acquisition and retargeting campaigns.
  • If an event is attributed to both retargeting and user acquisition campaigns, only the retargeting event is included in KPIs returned, meaning is_primary=true
  • Format: String
  • Example: "cohort_type": "user_acquisition"
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. 

  • Format: Integer
  • Default: 1 
  • Example: "min_cohort_size": 50
No

from 

Lower bound of the LTV attribution date range. The value can be up to 180 days before the current date.

  • Format: String yyyy-mm-dd
  • Example: "from": "2020-01-02"
Yes
to

Higher bound of the LTV attribution date range

  • Number of the days in the range: 1-31 days
  • For a single day: from and to values are identical. 
  • Format: yyyy-mm-dd
  • Example: "from": "2020-01-01", "to": 2020-01-31 is 31 days.
Yes
 

 

 

filters

Filter the data and period days returned. Select filters from the filter dimensions list.

  • Example limit to specific Geos: "filters": {"geo": "US"} includes only users attributed to the United States. 
  • Restrict period (cohort) days: The period filter restricts the days for which measures are returned. If no period filter is set (default) all possible periods are returned being: 0,1,2,..30, 60, 90, and 180. Example filter with period
  • Format: Strings in a nested JSON
 No

Use groupings to include additional columns and make your reports less granular.

Grouping parameters

Parameter

Values Mandatory 

groupings

  • Select 1-4 groupings from the grouping dimensions list.
  • Format: Strings in an array
  • Example: "groupings": ["af_ad", "c", "af_c_id", "af_prt"]
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.
Available KPIs and associated functions
    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 roi - - - -
Optional Sessions - -
Optional uninstalls - - -

Parameter

Values Mandatory parameter

kpis

Select one KPI from the KPIs available. In the future, we plan to allow the selection of multiple KPIs.

  • For each KPI requested, all functions are returned. 
  • Format: Strings in an array 
  • Example A: "kpis": ["sessions"]
  • Example B: "kpis": ["event_name"]
Yes

KPI format parameters set the format of the KPIs returned. 

Presentation of KPI functions

Parameter

Values Mandatory 

preferred_currency

KPI revenue currency

  • If true, revenue is returned using the app-specific currency set in the platform. 
  • [Default] If false, results return in USD.
  • Format: Boolean 
  • Platform UI version: True

 No

preferred_timezone

Time zone of data ranges

  • If true, times are expressed using the app-specific time zone set in the platform.
  • [Default] If false, times are expressed using UTC time zone.
  • Format: Boolean 
  • Platform UI version: True

 No

aggregation_type

  • cumulative
  • on_day

"aggregation_type": "cumulative"

Format: String

Yes

per_user

Divide the KPI function by the number of app users. Applies only to relevant KPIs.

  • If true, KPI values are divided by the number of users in the cohort.
  • If false, KPI values are not divided by the number of users.
  • Format: Boolean 
  • Example if true: total revenue is $1000, the number of app users is 500, the value returned is $2. 
 No

List of group by and filter by dimensions

Available grouping and filter 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

Attributed Touch Type

attributed_touch_type

Adset

af_adset

Adset ID

af_adset_id

 

Country

geo

Date (event date) 

date

Period

period

x

Example

CurlPython

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 <api_token_placeholder>' \
-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: CSVJSON

Additional information

Response codes and troubleshooting

Response codes

Response code 

Message

Remark 

200 OK

Valid data returned

200 Empty  The query was valid but no data was found matching the query. 
401 Unauthorized The authorization token is not legal
404 Not found
  • Eliminate any network, firewall, etc.  related problems. 
  • Ensure that the App ID specified in the endpoint is authorized for Cohort API
  Unprocessable entity Error message details are contained in the response body

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
CSV file name structure depends on the API query
Variable Possible values
aggregation_type
  • on_day
  • cumulative
per_user
  • per_user 
  • False: Null 
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, then the users who attributed (installed) during this period is included in the report. No other data is included. 

  • The value of the period can be one or more of the following 0-30, 60, 90, 180. For example, 0, 1, 2, 30, 180. 
  • When no filter period is specified, all possible values are returned, this means 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. 
  • If no filters period is specified, then all periods are returned, meaning 0-30, 60, 90, and 180. 

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

mceclip1.png

Results

mceclip0.png

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

CohortMapping.jpg

Cohortmapping2.jpg

Difference between aggregation types

CohortRevnueCumulative.jpg

Traits and limitations

Trait
Trait Yes  / No x Remarks 
Ad network access  x  
Agency access x  
Agency transparency x The media source of agency-driven traffic is always the agency and not the original media source. The Cohort UI version in the platform behaves similarly. 
App-specific time zone  
App-specific currency   
Size limitations None  
Throttling

 API call-rate limited to 60 calls per minute per account  

Organic data Available
Non-organic data Available
Data freshness  Daily  
Historical data Earliest conversion data (install or retarget) supported: January 1, 2019
Team member access x The authorization token is available to the account admin in the dashboard.
Was this article helpful?