Master API - customized aggregate data API

1. 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 API 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. 

Master API data freshness

• Data freshness:
  • Master API data is calculated daily. The updated data is available to you within 24-48 hours depending on your app-specific time zone.  
  • Use the data freshness endpoint detailed here to find out if your data is ready. 
• Data freshness endpoint:
  • The data freshness endpoint returns the date of the most recent date available. The format is: yyyy-mm-dd, for example, 2019-12-31.
  • Example: On January 2, 2020, you want to get the data for all 31 days of December 2019. Before submitting the Master API request for December, query the data freshness endpoint to ensure that December 31, 2019 is available. This means that the endpoint should return a value that is greater or equal to 2019-12-31. 

https://hq1.appsflyer.com/master/lastupdate?api_token={token}

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.

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. 

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".

kpis=installs,loyal_users_rate&calculated_kpi_3days_retention=
retention_day_1%2Bretention_day_2%2Bretention_day_3

kpis=installs&calculated_kpi_rev_per_impression=revenue%2Fimpression

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)

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.

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.

• 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.

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:

1. Replace the app name from com.greatapp to your android or iOS app's ID
2. Replace [TOKEN] with your account's API token
3. Replace the from and to dates to your preferred date range
4. Change the KPIs according to your preferences
5. If your app has a different timezone or currency than the default UTC±00:00 and USD add &timezone=preferred and/or &currency=preferred to the query URL

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 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.
• 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 will return “N/A”.

• Maximum lines count: 200K

Troubleshooting

This section discusses common Master API errors and how to handle them.

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.app

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