Cohort API

Premium
For:
Marketers
Last update:

At a glance: Cohort API provides advertisers a programmatic way to get Cohort data. Use the API to integrate Cohort data into BI and marketing automation systems.

Cohort API

The Cohort API is used to get cohorted campaign performance data from the AppsFlyer platform. It is functionally equivalent to the Cohort dashboard. 

To use Cohort and retention, you define the data that you want to view. You select users from an app and segment them by conversion time. Cohort metrics like revenue, ROI, and event conversion rates are available. Break the cohort down, for comparison purposes, into dimensions like campaign or media source. The result returns as a CSV or JSON file. You can use the results to uncover patterns or changes in performance over user or campaign life cycles.

See Cohort use cases.

To use Cohort API:

  1. AppsFlyerAdmin_us-en.pngGet the API token. An admin needs to retrieve the token.
  2. Give your developer the API token to be used in the authentication header.
  3. Give your developers the parameters to input when they make the API call, as described in the sections that follow. The parameters determine what the report focuses on, how it's organized, and provide a reporting timeframe.
  4. Tell your developer to follow their Cohort API instructions in the developer hub.

Cohort API parameters

Use the following parameters to get the necessary data. 

Parameter name

 Description Mandatory 

bearer

API token used in the API authentication header.

 Yes

cohort _type

Cohort attribution (conversion) type is one of the following: user_acquisition, retargeting, unified

  • 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
  • Minimum value allowed: 1. Don't send 0 (Zero)
  • Default: 1 
  • Example: "min_cohort_size": 50
 No

from 

Lower bound of the LTV attribution date range. The earliest date supported is 720 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

granularity

Hourly granularity for the previous 72 hours by setting  "granularity": "hour" and setting the from and to range to include the time of day.

  • Format: yyyy-mm-dd hh:mm:ss
  • Example:
"granularity": "hour", "from": "2021-12-01 14:00:00", "to": "2021-12-03 11:00:00", 		No

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.

  • [Default] If false, complete days return.
  • If true, up to 180 cohort days return, including days having incomplete data. 
  • Format: Boolean
  • Platform UI version: false

Example: On May 10, the number of complete cohort days for users converting during April 1-30, is 10. 

  • If false [default], cohort days 0-9, return. This is the number of days (10) between the last conversion date and today. 
  • If true, cohort days 1-40 return. Days 11-40 contain partial data and do not return. For example, since April 20, only 20 days have elapsed, and so on.

Note: Partial data is only allowed when the aggregation type is cumulative.

  No

filters

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

  • Format: Strings in a nested JSON. Values need to be in an array.
  • 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-180. 
  • Default: If no period filter is set the days 0-30, 60, 90, and 180 return. Example filter with period
 No

groupings
  • Use grouping parameters to include additional columns and make your reports less granular.
  • Select 1-7 groupings from the grouping dimensions list.
  • Format: Strings in an array
  • Example: "groupings": ["af_ad", "c", "af_c_id", "af_prt"]
 Yes

kpis

 KPIs are the metrics used for gaining insights into the behavior of your app. Learn how to select and format KPIs Yes
preferred_currency A parameter that sets the format of the KPIs returned. Learn how to format KPIs No
preferred_timezone A parameter that sets the format of the KPIs returned. Learn how to format KPIs No
aggregation_type A parameter that sets the format of the KPIs returned. Learn how to format KPIs Yes
per_user A parameter that sets the format of the KPIs returned. Learn how to format KPIs No

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.
  • For each KPI requested, all functions are returned. 
  • Format: Strings in an array 
    • Example A: "kpis": ["sessions"]
    • Example B: "kpis": ["event_name"]
    Functions
Default/ Optional  KPI (Dimensions name)  Count cvr (conversion rate) Rate Sum Unique users
Number Percentage Percentage Number Number
Always users Y - - - -
Always ecpi - - Y - -
Always cost - - - Y -
Optional "event_name"(4)  Y Y - Y (3) Y
Optional revenue Y - - Y -
Optional roas - - Y - -
Optional roi - - Y - -
Optional sessions Y - Y - Y(1)
Optional uninstalls (2) Y - Y - -

(1) Unique sessions returns when aggregation_type=on_day

(2) Not available when cohort_type=unified 

(3) Sum means the total revenue generated by the event. In the report, this is denoted by sum_event_name"

(4) Note! Event names are case-sensitive

Formatting KPI functions

The following parameters set the format of the KPIs returned. 

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 timezone 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

Group by and filter dimensions

Dimension name 

Dimension API value

Groupings

Filters

Ad

af_ad

Y

 Y

Ad ID

af_ad_id

Y

 Y

Campaign

c

Y

 Y

Campaign ID

af_c_id

Y

 Y

Channel

af_channel

Y

 Y

Media Source

pid

Y

 Y

Sub Param 1

af_sub1

Y

 Y

Keywords

af_keywords

Y

 Y

Agency

af_prt

Y

 Y

Conversion Type (1) 

cohort_type

Y

 Y

Site ID

site_id

Y

 Y

Revenue Type (2)

revenue_type

x 

 Y

Attributed Touch Type (3)

attributed_touch_type

Y

 Y

Adset

af_adset

Y

 Y

Adset ID

af_adset_id

Y

 Y

Country

geo

Y

 Y

Date (install/re-attribution/re-engagement date in the context of the cohort_type selected) 

date

Y

 x 

Period

period

Detailed explanation

 

x

Y

Notes: 

Dimension options:

(1) Conversion Type:  user_acquisition, retargeting(re-engagement and re-attribution), unified

  • When exporting:
    • re-engagement will show as retargeting
    • re-attribution will show as reattr

(2) Revenue Type: regular, ad_monetization

(3) Attributed Touch Type: click, impression, TV, pre-installed

Additional information

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-180. For example, 0, 1, 2, 30, 180. 
  • If no period is specified, the default values of 0, 1, 2, and so on to 30, 60, 90, and 180 return.  

 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.
  • The query specifies the aggregation type as "cumulative". Change to "on_day" if you want on-day data.
  • 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": "cumulative",
    "per_user": false,
    "groupings": [
        "pid"
    ],
    "kpis": [
        "revenue"
    ]
}

Raw data

mceclip1.png

Results

mceclip0.png

Traits and limitations

Trait Remarks 
Ad network access 

No
Agency access No
Agency transparency Not supported. The media source of agency-driven traffic is always the agency and not the original media source.
App-specific time zone Yes
App-specific currency  Yes
Size limitations None
Rate limitation
  • API call-rate limit: 60 calls per minute and 50,000 calls a day per account
  • Queries return up to 30,000 rows
Organic data Available
Non-organic data Available
Cost data limitation
  • Cost data is only for campaigns with at least 1 recorded install.
  • AppsFlyer does not report cost data for keywords that contain uppercase letters in the cohort report or cohort API
  • You can't combine some groupings combinations with cost. For example, Meta ads can have either geo or channel groupings but not both. The exact combination of groupings is ad network dependent.
Data freshness

Data freshness depends on partial_data as follows: 
Historical data Daily cohort: 2 years
Account user access The authorization token is available to admin users in the dashboard
Ad revenue

For af_ad_revenue events, the unique users metric isn't available when the aggregation type is:

  • Cumulative.
  • "On day," for dates between October 5, 2022-February 16, 2023.
Weekly and monthly groupings

Weekly and monthly dimension groupings aren't available with the Cohort API. Use the Cohort dashboard.
Cohort API period
  • The conversion period is referred to as 0 (Hour 0 or Day 0). The next period after the conversion is referred to as 1 (Hour 1 or Day 1), and so on.
  • In AppsFlyer a cohort period doesn't take into account the specific install timestamp. Rather, cohort hours are rounded down to the nearest hour, and cohort days, are based on the calendar day. This may cause discrepancies when comparing AppsFlyer cohort data to the cohort data of other networks, where all cohort periods are determined by the specific install timestamp (meaning an hour is 60 minutes post-install timestamp, and a day is the 24-hour post-install period after the install timestamp). 
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.
  • Earliest date supported: 730 days before the current date. Meaning 2 years
  • Maximum query range: 60 days.
Reinstalls
  • If post-reinstall events are considered unattributed organic:
    • They're included only as of May 26, 2024. Learn more
    • The install time is based on the device_download_time field.
    • They aren't counted toward unique user and retention measurements.
  • If post-reinstall events are attributed to the first install, they're always included. Learn more
Cohort API for partners

Access to the Cohort API for marketing partners is being deprecated as of September 15th, 2024. Marketing partners are encouraged to enable Data Locker to ensure continued access to customer data.