Master API - Customizable Aggregated Data API

Introduction

AppsFlyer's new customizable aggregated data API allows you to create your own report containing Lifetime Value (LTV), Retention and Activity-based KPIs, for either one or all of your apps. In addition, you can define the different groups according to which you want to view the data.  The data is available in either CSV or JSON formats.

To use the API, compose the URL which defines the data that you want to view.

Master API is an AppsFlyer premium feature. 

API Endpoint

Every call to the Master Report API must begin with the following endpoint:

https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=[app_id]&from=[from_date]&to=[to_date]


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.

Additional Parameters

Parameter Description Example Mandatory?

api_token

API token as appears under the API Access page in the dashboard

123510e9-1111-2222-3333-123bd8eeca9f

Yes

from

Start date

2016-08-02, 2017-w23

Yes

to

End date

2016-08-08, 2017-w24

Yes

app_id

Represents the apps included in the reports.  Either comma separated or "all". 

app_id=app_id1,app_id2

app_id=all

Yes 

groupings

comma separated, representing the different group by parameters for the selected query

groupings=pid,geo

Yes

kpis

comma separated – See below

kpis=installs,click, impressions,sessions,retention_day_7

Yes

pid

Used for filtering the media source name, 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

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

Available Groupings

These are for collecting the data into groups to allow easier and more accurate examination of the information.

Dimension Display Name LTV KPIs Retention KPIs Activity KPIs

app_id

App ID

Yes

Yes

Yes

pid

Media Source

Yes

Yes

Yes

af_prt

Agency

Yes

Yes

Yes

c

Campaign

Yes

Yes

Yes

af_adset

Adset

Yes

Yes

Yes

af_ad

Ad

Yes

Yes

Yes

af_channel

Channel

Yes

Yes

Yes

af_siteid

Publisher ID

Yes

Yes

Yes

af_keywords

Keywords

Yes

Yes

Yes

is_primary

Is Primary Attribution 

Yes

No

Yes

af_c_id

Campaign ID

Yes

No

Yes

af_adset_id

Adset ID

Yes

No

Yes

af_ad_id

Ad ID

Yes

No

Yes

install_time

Install Time

Yes

Yes

Yes

attributed_touch_type 

Touch Type

Yes

Yes

Yes

geo

GEO

Yes

Yes

Yes

List of KPIs

The Key Performance Indicators (KPI) are the metrics used for gaining an insight into the behavior of your app in different ways.  Click each tab to view the available KPIs under their associated group.

LTV Retention Activity Cohort Protect360
Lifetime Value - Aggregated Events cohorted by install day up and until today
KPI 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 unique users who performed the event
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

Report Time Granularity

Master API has two time granularity options:
  • Daily
  • Weekly
You can determine the desired granularity according to the time range selected. KPIs are displayed in accordance with your selection of either daily or weekly granularity.
Exact week numbers can be found here.

 Example

For a report using Daily granularity choose a date range such as From=2017-08-15&to=2017-08-17 and for Weekly granularity choose From=2017-w27&to=2017-w28

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.

Generally, 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, which have their own API, usually support cost data with only some of the available dimensions.

In these cases cost data is not available:

  • Network doesn't have any cost data related to it
  • Self-reporting network does support cost data, but not with the specific requested dimensions. For example, Google Adwords doesn't support cost data if the group by is GEO.

For the full list of ad networks supporting cost data click here.

Sample Requests

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 (GMT) 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/com.greatapp/master_report/v4?api_token=[TOKEN]
&from=[yyyy-mm-dd]&to=[yyyy-mm-dd]&pid=facebook
&groupings=pid,c,af_adset_id,af_ad_id
&kpis=installs,clicks,impressions,sessions,loyal_users,cost,revenue,arpu_ltv,roi
Elaborate AdWords Report
Compare all your Adwords ads performance:
https://hq.appsflyer.com/export/com.greatapp/master_report/v4?api_token=[TOKEN]
&from=[yyyy-mm-dd]&to=[yyyy-mm-dd]&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):
https://hq.appsflyer.com/export/com.greatapp/master_report/v4?api_token=
[TOKEN]&from=[yyyy-mm-dd]&to=[yyyy-mm-dd]&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/com.greatapp/master_report/v4?api_token=[TOKEN]
&from=[yyyy-mm-dd]&to=[yyyy-mm-dd]&groupings=af_keywords
&kpis=roi,arpu_ltv,average_ecpi,installs,loyal_users_rate,cost,revenue
Agencies Performance Report
Compare performance of all agencies working for you:
https://hq.appsflyer.com/export/com.greatapp/master_report/v4?api_token=[TOKEN]
&from=[yyyy-mm-dd]&to=[yyyy-mm-dd]&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 Tracking Affiliates):
https://hq.appsflyer.com/export/com.greatapp/master_report/v4?api_token=[TOKEN]
&from=[yyyy-mm-dd]&to=[yyyy-mm-dd]&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/com.greatapp/master_report/v4?api_token=[TOKEN]
&from=[yyyy-mm-dd]&to=[yyyy-mm-dd]&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/com.greatapp/master_report/v4?api_token=[TOKEN]
&from=[yyyy-mm-dd]&to=[yyyy-mm-dd]&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:
https://hq.appsflyer.com/export/com.greatapp/master_report/v4?api_token=[TOKEN]
&from=[yyyy-mm-dd]&to=[yyyy-mm-dd]&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

 Important Notes

  • If the Admin changed the preferred time zone in the dashboard within the requested time range, the generated report contains values from the last change only.
  • 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.
  • If all apps have the same configuration (whether by default or not), the common configuration is used. Otherwise, (different configurations per app), GMT and USD are used.
  • Maximum lines count: 200K
  • Localization (time zone and currency change) is not supported in Weekly Retention KPIs
Was this article helpful?
1 out of 1 found this helpful