At a glance: Get selected LTV, activity, retention, cohort, and Protect360 campaign performance KPIs by API, in CSV or JSON format. Select 1 or more apps.
Master API—user acquisition metrics via API
Master API:
- Lets you get selected LTV, activity, retention, cohort, and Protect360 campaign performance KPIs. The KPIs available are the equivalent KPIs of those found in the Overview, Activity, Retention, Cohort, and Protect360 dashboards.
- Is calculated daily. The updated data is available to you within 24-48 hours, depending on your app-specific timezone.
- Is the infrastructure upon which the AppsFlyer pivot table is built.
To use Master API, you define the data that you want to view (similar to the implementation of the Pull API). The result returns as a CSV or JSON file.
To use Master API:
-
Get the API token. An admin needs to retrieve the token.
- Give your developer the API token to be used in the authentication header.
- 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.
- Tell your developer to follow their Master API instructions in the developer hub.
API parameters
Parameter Value Mandatory app_id - App identifier, as found in AppsFlyer.
- Insert the app ID exactly as found in AppsFlyer
- Prefix iOS apps with id
- Use all app IDs to query for all your apps
Yes from Lower-bound of the LTV attribution date range. - Format: String yyyy-mm-dd
- Example:
from: 2020-01-02
Yes to Upper-bound of the LTV attribution date range - Number of the days in the range: 1-31 days
- For a single day:
fromandtovalues are identical. - Format: yyyy-mm-dd
- Example:
from: 2021-01-01, to: 2021-01-31is 31 days.
Yes Groupings Group by parameters, separated by a comma. See the Groupings table for the list available
Example:
groupings=pid,geoYes KPIs List of KPIs to include, each separated by a comma. See the KPI table that follows for a list of KPIs.
Example:
kpis=installs,clicks, impressions,sessions,retention_day_7Yes Filters Data can be filtered using one or more filter options. No Currency To return data using the app-specific currency set currency=preferred No Timezone To return data using the app-specific timezone set timezone=preferred. See localization rules No Format By default, the response data is received in CSV file format. If you prefer to get the data in JSON format, select format=json.No Groupings
These dimensions are used for collecting the data into groups to allow easier and more accurate examination of the information. You can find descriptions of these fields here.
Group by
API nameGroup by display name LTV KPIs Retention KPIs Activity KPIs Protect360 Cohort app_id App ID Yes Yes Yes Yes Yes pid Media source Yes Yes Yes Yes Yes af_prt Agency Yes Yes Yes Yes No c Campaign Yes Yes Yes Yes Yes af_adset Adset Yes Yes Yes No No af_ad Ad Yes Yes Yes No No af_channel Channel Yes Yes Yes Yes No af_siteid Publisher ID Yes Yes Yes Yes Yes af_keywords Keywords Yes Yes Yes No No is_primary Is primary attribution Yes No Yes Yes No af_c_id Campaign ID Yes No Yes Yes No af_adset_id Adset ID Yes No Yes No No af_ad_id Ad ID Yes No Yes No No install_time Install Time Yes Yes Yes* Yes Yes attributed_touch_type Touch Type Yes Yes Yes Yes No geo Geo Yes Yes Yes Yes Yes * In the context of Activity KPIs, regard install time as event time. KPIs
KPIs are the metrics used for gaining insights into the behavior of your app. The KPIs are grouped by type in the sections that follow.
LTV
Lifetime Value - Aggregate Events segmented by install day up and until today
KPI API name Description impressions Number of impressions within the selected time frame clicks Number of clicks within the selected time frame installs Number of installs within the selected time frame cr Conversion Rate sessions Number of sessions created by the users who installed within the selected time frame loyal_users Number of loyal users who installed within the selected time frame loyal_users_rate Loyal users/installs cost Total cost in the selected time frame. See limitations. revenue Lifetime revenue generated by the users who installed in the selected time frame roi Return on Investment over a certain time frame arpu_ltv Average revenue per user, for the users who installed in the selected time frame average_ecpi Effective Cost per Installation (eCPI) over a certain time frame. Available only if cost and installs are included in the call. uninstalls Uninstalling users, who installed in the selected time frame uninstalls_rate Uninstallation rate event_counter_[event_name] Number of event occurrences unique_users_[event_name] Number of unique users who performed the event sales_in_usd_[event_name] Revenue reported as part of the reported events Retention
Retention is a measure of how many existing users are active in your app.
Note:
- The maximum retention day number is 30 days post-install, where day 0 is the install day. This means that value [x] cannot exceed 30.
- If you request retention_day_1, before the data for that day is available then the metric that returns relates to users installing on the previous day. For example, on Jan 2, you request retention_day_1 for users who installed on Jan 1. Because the metric isn't yet available, the metric that returns relates to users who installed on Dec 31.
KPI Description retention_day_[x] Number of retained users at day X retention_rate_day_[x] Number of retained users at day X out of installing users Activity
App activity occurring during a selected date range. Note: Activity KPIs include unified data (UA and retargeting together).
KPI Description activity_average_dau Average daily active users (DAU) within the selected time frame activity_average_mau Average monthly active users within the selected time frame (one MAU day represents the unique users in the preceding 30 days) activity_average_dau_mau_rate Average DAU/MAU rate activity_average_arpdau Average revenue per daily active user - the average revenue of a given day out of all unique users activity_sessions Number of sessions performed within the selected time frame activity_revenue Revenue reported within the selected time frame activity_event_counter_[event_name] Number of events generated by users within the selected time frame activity_sales_in_usd_[event_name] Revenue reported as part of the reported events within the selected time frame activity_average_unique_users_[event_name]
Average unique users performing a given event within the selected time frame Cohort
AppsFlyer Cohorts provide advertisers with the ability to view and compare different metrics for multiple cohorts over different time frames.
Note:
- Rounding errors: Cohort per user KPIs are calculated using four decimal places. This means that if the calculated value per user is < 0.0001 then this shows as 0. For example, the number of users is 100,000, and total revenue is $9. The revenue per user is 9/100000=0.00009. As 0.00009<0.0001 the value shown will be 0.
- Cohort days: The maximum cohort day number is 90 days post-install where day 0 is the install day. The cohort day value [x] must be in the range of 1-90. Note: cohort_day_0 isn't supported in Mater API, even though it's supported in the Cohort dashboard.
- Master API vs. Cohort API and Cohort dashboard: Results may differ due to different handling of reinstalls and timing issues.
Sessions
KPI Description cohort_day_[x]_total_sessions_per_user Cohort Day x - Cumulative sessions per user up to day x (including day x) cohort_day_[x]_sessions_per_user Cohort Day x - Sessions on day x only from the cohort cohort_[x]_days_total_sessions_per_user Replaces specifying KPIs Cohort_day_1_total_sessions_per_user to Cohort_day_x_total_sessions_per_user on the URL.
For example: cohort_3_days_total_sessions_per_user on the URL produces 3 report columns:
Cohort_day_1_total_sessions_per_user+ Cohort_day_2_total_sessions_per_user+Cohort_day_3_total_sessions_per_userRevenue
KPI Description cohort_day_[x]_total_revenue_per_user Cohort Day x - Cumulative revenue per user up to day x (including day x) cohort_day_[x]_revenue_per_user Cohort Day x - ARPU received on day x only from the cohort cohort_[x]_days_total_revenue_per_user Replaces specifying KPIs Cohort_day_1_total_revenue_per_user to Cohort_day_x_total_revenue_per_user.
For example: cohort_3_days_total_revenue_per_user on the URL produces 3 report columns:
Cohort_day_1_total_revenue_per_user+ Cohort_day_2_total_revenue_per_user+Cohort_day_3_total_revenue_per_usercohort_day_[x]_total_event_[eventname]_revenue_per_user Cohort Day x accumulative revenue per user according to specific in-app event cohort_day_[x]_event_[eventname]_revenue_per_user Cohort Day x revenue per user according to specific in-app event Events
KPI Description cohort_day_[x]_total_event_[eventname]_per_user Cohort Day x - Cumulative events per user up to day x (including day x) cohort_day_[x]_event_[eventname]_per_user Cohort Day x - Events received on day x only from the cohort cohort_[x]_days_total_event_[eventname]_per_user Replaces specifying KPIs events to Cohort_day_x_total_events_per_user.
For example: cohort_3_days_total_events_per_user on the URL produces 3 report columns:
Cohort_day_1_total_events_per_user+ Cohort_day_2_total_events_per_user+Cohort_day_3_total_events_per_userProtect360
Protect360 KPIs
Description KPI Installs Total protect360_total_installs Blocked blocked_installs Blocked % blocked_installs_rate Post-attribution post_attribution_installs Post-attribution % post_attribution_installs_rate Total fraudulent installs total_fraudulent_installs Fraudulent installs % fraudulent_installs_rate Fake installs Real-time block real_time_fake_installs Post-attribution fraud post_attribution_fake_installs Hijacked installs Real-time block real_time_hijacked_installs Post-attribution fraud post_attribution_installs_hijacked_installs Validation rules Blocked installs validation_rules_blocked_installs Blocked attribution validation_rules_blocked_attribution Fake installs block breakdown Blocked site ID blacklist blocked_installs_siteid_blacklist Post-attribution site ID blacklist post_attribution_installs_siteid_blacklist Blocked bots blocked_installs_bots Post-attribution bots post_attribution_installs_bots Blocked behavioral anomalies blocked_installs_behavioral_anomalies Post-attribution behavioral anomalies post_attribution_installs_behavioral_anomalies Blocked install validation blocked_installs_install_validation Hijacked installs block breakdown Blocked install hijacking blocked_installs_install_hijacking Post-attribution install hijacking post_attribution_installs_installs_hijacking Blocked CTIT anomalies blocked_installs_ctit_anomalies Post-attribution CTIT anomalies post_attribution_installs_ctit_anomalies Blocked click flooding blocked_installs_click_flood Post-attribution click flooding post_attribution_installs_click_flood Clicks Total protect360_total_clicks Blocked blocked_clicks % blocked_clicks_rate In-App Events Total protect360_total_in_apps Blocked blocked_in-app-events % blocked_in-app-events_rate Device farm indicators - new devices Installs install_fraud_new_devices_total Installs % install_fraud_new_devices_total_installs_rate Loyal user % install_fraud_new_devices_total_loyal_user_rate Device farm indicators - LAT devices Installs install_fraud_lat_devices_total Installs % install_fraud_lat_devices_total_installs_rate Loyal user % install_fraud_lat_devices_total_loyal_user_rate Click flooding indicators Conversion rate conversion_rate Click flooding indicators - CTIT Over 60 minutes click_flood_over_1_hour_rate Over 5 hours click_flood_over_5_hours_rate Calculated KPIs
In addition, to the KPIs described previously, you can add calculated KPIs to your master API reports. This enables you to have your own calculated reports included in your Master API reports.
You can insert any number of built-in KPI objects in the calculated KPI formulas. Each calculation KPI object includes a key and a value. The key is the name you give the KPI and the value is the KPI formula.
Standard arithmetic operators are supported: addition (+) encoded as %2b, subtraction (-), multiplication (*), division (/) encoded as %2f.
Calculated KPI field keys must start with "calculated_kpi_", followed by any valid string, such as, "calculated_kpi_purchaserate".
Example
First three days combined retention
kpis=installs,loyal_users_rate&calculated_kpi_3days_retention= retention_day_1%2Bretention_day_2%2Bretention_day_3
Average revenue per impression
kpis=installs&calculated_kpi_rev_per_impression=revenue%2Fimpression
Cohort day 7 ROI
kpis=installs,roi,arpu_ltv,cost,revenue&calculated_kpi_roi_day_7= (cohort_day_7_total_revenue_per_user-average_ecpi)%2Faverage_ecpi
Filters (optional)
Parameter Description Example Mandatory? pid - Used for selecting the rows, in which the specified media source/s are displayed.
- Comma-separated multiple selection is supported.
pid=organic,applovin_int No c - Used for filtering by campaign name.
- Comma-separated multiple selection is supported.
c=my_sample_campaign No af_prt - Used for filtering by agency name.
- Comma-separated multiple selection is supported.
af_prt=moburst No af_channel - Used for filtering by channel name.
- Comma-separated multiple selection is supported.
af_channel=Instagram No af_siteid - Used for filtering by publisher ID.
- Comma-separated multiple selection is supported.
af_siteid=12345678 No geo - Used for filtering by country.
- Comma-separated multiple selection is supported.
geo=US,DE No Localization
Local currency and app-specific timezone are set on the app settings page. Master API data can extract the data using either the system's default currency and timezone or using the app-specific timezone and currency.
The following applies:
- Using the app-specific timezone/currency is supported only if all apps have the same timezone/currency. Otherwise, UTC and USD are used. Timezone and currency are separate. Meaning that if the currency of all apps is the same but the timezones aren't, then you can use the app-specific currency but not the app-specific timezone.
- If the preferred timezone was changed in the dashboard within the requested time range, the generated report contains values starting from the most recent timezone change.
Use the following parameters to select the app-specific setting. Note: If you don't use the preferred parameters, you get the default settings, which are USD for currency and UTC for timezone.
Parameter Description Example Mandatory? currency Monetary values are in the app-specific currency currency=preferred No timezone Timezone used is according to the app-specific timezone timezone=preferred No
Additional information
Traits and limitations
| Trait | Remarks |
|---|---|
| Cost data |
|
| Groupings | Specific groupings are only available for LTV KPIs, Activity, or Retention KPIs. The API returns N/A when the data for a specific KPI is not available. For example, requesting retention_rate_day_7 grouped by af_channel returns N/A. |
| Maximum rows per report | 200K |
| Event names | Master API currently doesn't support event names that include a forward-slash / . To overcome this limitation, avoid the user of / in event names. |
| Processing time | Selecting more than one app increases the processing time and the response may take longer. |
| Date range | Timeframe granularity is daily. |
| Agencies | Master API not available |
| Ad networks | Master API not available |
| Historical data |
|
| Retargeting |
|