At a glance: Master API enables you to create customized aggregate reports. You select the apps, KPIs, and report groupings to include in the report. The KPIs available are the same KPIs as found in the lifetime value (LTV), retention, cohort, activity, and Protect360 dashboards.
- To use Master API, compose the URL which defines the data that you want to view. This is similar to the implementation of the Pull API, the result is returned as a CSV file.
- Master API is the infrastructure upon which AppsFlyer's pivot table is built.
- Master API is not available for agencies and partners.
Master API structure
Master APIs consist of the following parts:
- Endpoint URL: ends in a ?
- Parameters: both mandatory and optional. Between each parameter a & is required
Master API call
The Master API URL endpoint is as follows:
https://hq.appsflyer.com/export/master_report/v4?Master AP with mandatory parameters
https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=[app_id]&from=[from_date]&to=[to_date]&groupings=[list]&kpis=[list]
- The names of KPIs, groupings, and other parameters are in lowercase.
- The API token is the same API token that is used with Pull API.
- The API token changes when the account admin changes. If the account admin changes, you must update Master API URLs with the new API token.
The following table describes the API parameters.
| Parameter | Description | Example | Mandatory |
|---|---|---|---|
|
api_token |
API token identifying your account. Retrieve the token in the API Access page in the dashboard:
|
123510e9-1111-2222-3333-123bd8eeca9f |
Yes |
|
from |
Start date (date or week number) |
2016-08-02, 2017-w23 |
Yes |
|
to |
End date (date or week number) |
2016-08-08, 2017-w24 |
Yes |
|
app_id |
Apps to include in the report:
|
|
Yes |
|
groupings |
Group by parameters, separated by a comma, for the selected query. See the Groupings table for the list available |
groupings=pid,geo |
Yes |
|
kpis |
List of KPIs to include, each separated by a comma. See the KPI table that follows for a list of KPIs. |
kpis=installs,clicks, impressions,sessions,retention_day_7 |
Yes |
|
filters |
Optional filters. See the filters table. |
|
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 |
Yes |
No |
|
af_ad |
Ad |
Yes |
Yes |
Yes |
Yes |
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 |
Yes |
No |
|
af_ad_id |
Ad ID |
Yes |
No |
Yes |
Yes |
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 |
KPIs
KPIs are the metrics used for gaining an insight into the behavior of your app. The KPI's 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 |
| 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 |
| 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 |
Retention is a measure of how many existing users are active in your app.
Limitation: 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.
| 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 |
| retention_week_[x] | Number of retained users at week X |
| retention_rate_week_[x] | Number of retained users at week 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 |
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. This means that value [x] cannot exceed 90.
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: |
| KPI | Description |
|---|---|
| protect360_total_installs | Total Non-Organic Installs |
| blocked_installs | Total of installs blocked from: device rank, CTIT, installs validation and sited ID blacklist |
| blocked_installs_rate | Blocked Installs Rate |
| blocked_installs_device_rank | Blocked Installs Device Rank |
| blocked_installs_validation | Blocked Installs Validation |
| blocked_installs_siteid_blacklist | Blocked Installs Site ID Blacklist |
| blocked_installs_ctit_anomalies | Blocked Installs CTIT Anomalies |
| blocked_installs_bots | Blocked Installs Bots |
| blocked_installs_click_flood | Blocked Installs Click Flood |
| blocked_installs_hijacking | Blocked Installs Hijacking |
| protect360_total_clicks | Total Clicks |
| blocked_clicks | Blocked Clicks |
| blocked_clicks_rate | Blocked Clicks Rate |
| protect360_total_in_apps | Total Non-Organic In-App events |
| blocked_in-app-events | Blocked In-App Events |
| blocked_in-app-events_rate | Blocked In-App Events Rate |
| install_fraud_new_devices_installs | New Devices Installs |
| install_fraud_new_devices_installs_rate | New Devices Installs Rate |
| install_fraud_new_devices_loyal_user_rate | New Devices Loyal User Rate |
| install_fraud_lat_devices_installs | LAT Devices Installs |
| install_fraud_lat_devices_install_rate | LAT Devices Install Rate |
| install_fraud_lat_devices_loyal_user_rate | LAT Devices Loyal User Rate |
| install_fraud_suspicious_devices_installs | Suspicious Devices Installs |
| install_fraud_suspicious_devices_install_rate | Suspicious Devices Install Rate |
| install_fraud_suspicious_devices_loyal_user_rate | Suspicious Devices Loyal User Rate |
| install_fraud_clean_device_installs | Clean Device Installs |
| install_fraud_clean_device_install_rate | Clean Device Install Rate |
| install_fraud_clean_device_loyal_user_rate | Clean Device Loyal User Rate |
| click_flood_under_5_min_rate | Click Flood - CTIT Under 5 Minutes Rate |
| click_flood_from_5_to_60_min_rate | Click Flood - CTIT Over 5 Under 60 Minutes Rate |
| click_flood_over_60_min_rate | Click Flood - CTIT Over 60 Minutes Rate |
| contribution_rate | Contribution Rate |
| install_hijacking_up_to_10_sec_rate | Install Hijacking - CTIT up to 10 Seconds Rate |
| install_hijacking_10_to_30_sec_rate | Install Hijacking - CTIT 10 to 30 Seconds Rate |
| install_hijacking_over_30_sec_rate | Install Hijacking - CTIT Over 30 Seconds Rate |
Note
Event names are case-sensitive. Use the identical event names sent to AppsFlyer with KPIs containing event names.
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_3Average revenue per impression
kpis=installs&calculated_kpi_rev_per_impression=revenue%2FimpressionCohort 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_ecpiFilters (optional)
Time frame fields
- You use the time frame fields, To and From, to determine the desired granularity in the selected time range. KPIs are displayed in accordance with your selection of either daily or weekly granularity.
- When you select either weekly or daily granularity, ensure that the KPIs chosen correspond to the granularity level. To learn more, click here.
- Exact week numbers can be found here.
Example
- Daily granularity: Choose a date range such as
From=2017-08-15&to=2017-08-17 - Weekly granularity: choose a date range such as
From=2017-w04&to=2017-w12
Localization
You can set local currency and timezone for your apps on the app settings page. The same localization preferences can also be reflected on master API reports using the parameters below.
| Parameter | Description | Example | Mandatory? |
|---|---|---|---|
|
currency |
All monetary values in the report are according to the App's Admin's choice of currency |
currency=preferred |
No |
|
timezone |
The report is generated according to the App's Admin's choice of time. |
timezone=preferred |
No |
- If all apps have the same configuration (whether by default or not), the common configuration is used. Otherwise, (different configurations per app), UTC±00:00 and USD are used.
- Localization (time zone and currency change) is not supported in Weekly Retention KPIs
- If the preferred time zone was changed in the dashboard within the requested time range, the generated report contains values starting from the last change only.
Note
For results to appear in the Master API according to Time Zone, the timezone=preferred parameter must be used.
Response format
All the received fields in the response are according to V5 format.
By default, the response data is received in CSV file format. If you prefer to get the data in JSON format add &format=json to the URL.
Request examples
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 from com.greatapp to your android or iOS app's ID
- Replace [TOKEN] with your account's API token
- Replace the from and to dates to your preferred date range
- Change the KPIs according to your preferences
- If your app has a different timezone or currency than the default UTC±00:00 and USD add
&timezone=preferredand/or¤cy=preferredto the query URL
Compare all your 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=com.greatapp&from=[from_date]&to=[to_date]&groupings=is_primary&kpis=revenue
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
Cost data
Cost data, including eCPI, may not always be available. This depends on whether the network supports cost data, the type of the network, i.e. using AppsFlyer links or self-reporting, and the requested dimensions.
In general, all sources, including owned media, which use AppsFlyer's 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 at the same time (grouping by either of them separately is supported).
For the full list of ad networks supporting cost data click here.
Important Notes
- 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 will return “N/A”.
- Data Freshness: The data is aggregated on a daily basis. For users in time zone UTC - (minus) it may take up to 48 hours and for users in time zone UTC + (plus) it may take up to 24 hours for the report to be populated with data.
- Maximum lines count: 200K
Troubleshooting
This section discusses common Master API errors and how to handle them.
The supplied API token is invalid
Error message
The supplied API token is invalid
Error code
401
Description
The server could not authenticate the request. The API token is either missing or invalid.
How to solve
Make sure that the URL contains the correct API token. The API token is passed in the api_token parameter.
Unauthorized app-ids
Error message
Request id: <request_id>. Not authorized app-ids: <app_id>
Error code
416
Description
This error occurs when you make a request for data related to an app that is not listed in your dashboard.
How to solve
Verify that the app ID that you pass in the app_id parameter is the correct app ID.
Note
For Android, the app ID is the package ID.
For iOS, the app ID is the App ID rather than the bundle ID.
No KPIs provided
Error message
Request id: <request_id>. [Error] No kpis provided
Error code
403
Description
The master API provides aggregate reports. These reports require KPIs according to which data is aggregated.
How to solve
Specify the desired KPis in the kpis parameter.
Wrong API fields
Error message
Wrong API Fields: <api_field>
Error code
416
Description
One or more API fields in the request are incorrect. API fields can be specified in the kpis or groupings parameters.
How to solve
Make sure to list the correct API field name in the request. See the list of available KPIs or Groupings fields.
No groupings selected
Error message
No Groupings Selected
Error code
416
Description
The master API provides aggregate reports. These reports require KPIs according to which data is aggregated.
How to solve
Specify the desired groupings in the groupings parameter.
Weekly and daily data
Error code
403
Description
You cannot specify daily fields when querying for data that is aggregated weekly or vice versa.
How to solve
Specify weekly fields for weekly data:
https://hq1.appsflyer.com/master/v4?api_token=<API_TOKEN>&from=2019-w4&to=2019-w4&groupings=geo,pid&kpis=installs,retention_week_2&app_id=com.sample.appor daily fields for daily data:
https://hq1.appsflyer.com/master/v4?api_token=<API_TOKEN>&from=2019-08-01&to=2019-08-04&groupings=geo,pid&kpis=installs,retention_day_2&app_id=com.sample.app