Master API - customized aggregate data API

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 is used with Pull API.  To retrieve the API token, click your email > API Tokens.
• 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

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 apply:

• Using the app-specific time zone/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.  
• Localization 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 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. 

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:

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. You can get the report using app-specific time zone and currency by using the following:  &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