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}
Master API parameters
Parameter Description Example Mandatory

api_token

API token identifying your account. Retrieve the token in the API Access page in the dashboard:

  1. Go to page of the relevant app.
  2. Under Integration, click API Access.

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)

Note: Use the data freshness API (described in the previous section)  to retrieve the date of the last data update.  
 

2016-08-08, 2017-w24

Yes

app_id

Apps to include in the report:

  • List of apps separated by a comma
  • All apps
  • app_id=app_id1,app_id2
  • app_id=all
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. 

LTVRetentionActivityCohortProtect360
Lifetime Value - Aggregate Events cohorted 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
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

 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_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)

Time frame fields

The following time granularity options are available: Daily, Weekly
  • 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:

  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
Elaborate Facebook Report

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
Elaborate Google Ads Report
Compare all your Google Ads performance:
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
Specific Countries Report
For Example: US and Canada for North America for all apps in the account:
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	
Keywords Effectiveness Report
Compare ROI and other KPIs of users according to their used keyword for installing:
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
Agencies Performance Report
Compare the performance of all agencies working for you:
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
Affiliates Performance Report
Find the best affiliates that get you most installs from quality users under the media source 'affiliates' (more about attributing installs to affiliates):
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
Attribution Type Report
Do your best users come from clicks, impressions or organic?:
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
Retargeting Users Effectiveness Report
Which type of campaigns gets more revenue, UA or retargeting?
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
Networks Retention Report
Compare all networks installs for users retention on day 1, 7, 15, 22 and 30 after the install for all apps ?n the account:
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.

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

or 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
Was this article helpful?
1 out of 1 found this helpful