At a glance: Get selected LTV, activity, Protect360, and retention campaign performance KPIs by API, in CSV or JSON format. Select 1 or more apps.
Important!
- Support for this API will be discontinued on April 30, 2023 and Master API V2 will be the only supported method.
- The Master API V2 will be available for use on February 9, 2023.
Master API—user acquisition metrics via API
- KPIs available are the equivalent KPIs found in the Overview, Activity, and Protect360 dashboards.
- To use Master API, compose the URI defining the data that you want to view. This is similar to the implementation of the Pull API; the result returns as a CSV or JSON file.
- Master API:
- Is the infrastructure upon which the AppsFlyer pivot table is built.
- Is not available for agencies and partners.
Master 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 | https://hq.appsflyer.com/export/master_report/v4? |
HTTP method | GET |
Data freshness |
Data freshness endpoint:
|
API parameters
https://hq.appsflyer.com/export/master_report/v4?api_token=api_token
&app_id=app_id&from=yyyy-mm-dd&to=yyyy-mm-dd&groupings=groupings&kpis=kpis
Parameter |
Value | Mandatory |
---|---|---|
api_token | ![]() |
Yes |
app_id |
|
Yes |
from |
Lower bound of the LTV attribution date range.
|
Yes |
to |
Higher bound of the LTV attribution date range
|
Yes |
groupings |
Group by parameters, separated by a comma. See the Groupings table for the list available Example: |
Yes |
kpis |
List of KPIs to include, each separated by a comma. See the KPI table that follows for a list of KPIs. Example: |
Yes |
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 time zone 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 append |
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 name |
Group 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 an insight into the behavior of your app. The KPIs are grouped by type in the tabs that follow.
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%20name]* | Number of event occurrences |
unique_users_[event%20name]* | Number of unique users who performed the event |
sales_in_usd_[event%20name]* | Revenue reported as part of the reported events |
* Event name must be lower case |
Retention is a measure of how many existing users are active in your app.
Limitations:
- 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 |
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%20name]* | Number of events generated by users within the selected time frame |
activity_sales_in_usd_[event%20name]* | Revenue reported as part of the reported events within the selected time frame |
activity_average_unique_users_[event%20name]* |
Average unique users performing a given event within the selected time frame |
* Event names are case sensitive |
AppsFlyer Cohorts provides advertisers with the ability to view and compare different metrics per multiple cohorts over different time frames.
Limitations:
- 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, total revenue $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 1-90. Note cohort_day_0 isn't supported in Mater API. It is supported in 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: |
Revenue
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 on the URL. For example: cohort_3_days_total_revenue_per_user on the URL produces 3 report columns: |
cohort_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 on the URL. For example: cohort_3_days_total_events_per_user on the URL produces 3 report columns: |
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 KPIs in the calculated KPI formulas.
Standard arithmetic operators are supported: addition (+) encoded as %2b, subtraction (-), multiplication (*), division (/) encoded as %2f.
Calculated KPI field names 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, which the specified media source/s are displayed in. 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 |
Time frame fields
The following time granularity options are available: Daily.
You use the time frame fields, To and From, to determine the desired granularity in the selected time range.
Example
- Daily granularity: Choose a date range such as
From=2017-08-15&to=2017-08-17
Localization
Local currency and app-specific time zone are set on the app settings page. Master API data can extract the data using either the system default currency and time zone or using the app-specific time zone 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. Time zone and currency are separate. Meaning that if the currency of all apps is the same but the time zones not, then you can use the app-specific currency but not the app-specific time zone.
- If the preferred time zone was changed in the dashboard within the requested time range, the generated report contains values starting from the most recent time zone 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 time zone.
Parameter | Description | Example | Mandatory? |
---|---|---|---|
currency |
Monetary values are in the app-specific currency |
currency=preferred |
No |
timezone |
Time zone used is according to the app-specific timezone |
timezone=preferred |
No |
For results to appear in the Master API according to Time Zone, the timezone=preferred parameter must be used.
Example calls
To save you time, here is a list of Master API URLs you can cut and paste to get different reports. Before using a URL, make sure to:
- Replace the app name of com.greatapp to that of your app ID
- Replace [api_token ] with your API token
- Replace the from and to dates to the required date range
- Change the KPIs according to your requirements
- You can get the report using the app-specific time zone and currency by using the following:
&timezone=preferred
and/or¤cy=preferred
to the query URL
Compare Facebook ads performance:
https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=com.greatapp&from=[from_date]&to=[to_date]&pid=facebook
&groupings=pid,c,af_adset_id,af_ad_id
&kpis=installs,clicks,impressions,sessions,loyal_users,cost,revenue,arpu_ltv,roi
https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=com.greatapp,id123456789&from=[from_date]&to=[to_date]&pid=googleadwords_int
&groupings=pid,c,af_adset_id,af_ad_id
&kpis=installs,sessions,loyal_users,cost,revenue,arpu_ltv,roi
https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=all&from=[from_date]&to=[to_date]&groupings=geo,pid,c&kpis=
installs,clicks,impressions,sessions,loyal_users,cost,revenue,arpu_ltv,
roi&geo=us,ca
https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=com.greatapp&from=[from_date]&to=[to_date]&groupings=af_keywords
&kpis=roi,arpu_ltv,average_ecpi,installs,loyal_users_rate,cost,revenue
https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=com.greatapp,id123456789&from=[from_date]&to=[to_date]&groupings=af_prt,pid,c&kpis=installs,
loyal_users_rate
https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=com.greatapp&from=[from_date]&to=[to_date]&groupings=af_siteid&pid=affiliates
&kpis=installs,loyal_users_rate,arpu_ltv,retention_day_1,retention_rate_day_1,
retention_day_7,retention_rate_day_7,retention_day_15,retention_rate_day_15,
retention_day_30,retention_rate_day_30
https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=com.greatapp,id123456789&from=[from_date]&to=[to_date]&groupings=attributed_touch_type
&kpis=installs,sessions,loyal_users_rate,arpu_ltv
https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=all&from=[from_date]&to=[to_date]&groupings=pid,c
&kpis=installs,loyal_users_rate,retention_day_1,retention_rate_day_1,
retention_day_7,retention_rate_day_7,retention_day_15,retention_rate_day_15,
retention_day_22,retention_rate_day_22,retention_day_30,retention_rate_day_30
Limitations and troubleshooting
Limitations
- Cost data:
- Availability of different cost dimensions meaning adset, ad, geo, channel, and site ID is ad network dependent.
- To get eCPI: If the cost data is available, include both installs and cost in the call.
- In general, all sources, including owned media, which use AppsFlyer links and have the cost parameter on the links, fully support cost data, regardless of the requested dimensions. Self-reporting networks, with their own API, usually support cost data with only some of the available dimensions. For example, Facebook doesn’t support grouping by Geo and Channel in the same call. Grouping by either of them separately is supported.
- Campaigns that have cost data, but no installs data in the recent past (approx. 7 days), are not available via Master API.
- 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 having the 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.
Troubleshooting
Message |
Remark |
|
---|---|---|
200 OK |
|
|
401 Unauthorized | The supplied API token is invalid |
|
404 | Not found |
|
416 | No Groupings Selected |
|
403 | Unrecognized date format. | Check the dates and correct them |
403 | From date can't be after To date. | Check the dates and correct them |
403 | From and To dates must have the same granularity format. | Check the dates and correct them |
403 | No KPIs provided. | |
403 | One or more of the formula's operators are not supported when not Unicode. | |
403 | No calculated KPI name provided. | |
416 | Something went wrong. Please re-try to download in a minute, choose a narrower time range, or contact AppsFlyer support. |
|
416 | The requested time range is in UTC only (prior to the timezone change) | |
403 | Not authorized app-ids: <app_ids> |
|
416 | Please select authorized app-id | |
416 | No Groupings Selected | |
416 | Wrong API Fields |
The field doesn't exist or is not permitted |
416 | Other reason |
The report size exceeds 200K |