Using Master API—campaign performance KPIs

At a glance: Get campaign performance KPIs by API.

Master API—campaign performance KPI reporting

  • KPIs available are the equivalent KPIs found in the Overview, Activity, and Protect360 dashboards.
  • To use Master API, compose the URI defining the data that you want to view. This is similar to the implementation of the Pull API; the result returns as a CSV or JSON file. 
  • Master API:
    • is the infrastructure upon which the AppsFlyer pivot table is built. 
    • is not available for agencies and partners.
  • Data freshness of Master API: Daily.

Master API facts

Overview The API call consists of the path, headers, and a JSON containing the data query. Data is returned by default in a CSV file.
Path https://hq.appsflyer.com/export/master_report/v4?
HTTP method GET
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 facts

API parameters

https://hq.appsflyer.com/export/master_report/v4?api_token=api_token &app_id=app_id&from=from&to=to&groupings=groupings&kpis=kpis

Call parameters

Parameter

Value Mandatory
api_token  AppsFlyerAdmin_us-en.pngThe admin needs to retrieve the token. To retrieve the API token, click your email > API Tokens. Yes 
app_id
  • App identifier, as found in AppsFlyer.
  • Insert the app ID exactly as found in AppsFlyer
  • Prefix iOS apps with id
Yes
from

Lower bound of the LTV attribution date range.

  • Format: String yyyy-mm-dd
  • Example: "from": "2020-01-02"
Yes 
to  

Higher bound of the LTV attribution date range

  • Number of the days in the range: 1-31 days
  • For a single day: from and to values are identical. 
  • Format: yyyy-mm-dd
  • Example: "from": "2020-01-01", "to": 2020-01-31 is 31 days.
 Yes
groupings

Group by parameters, separated by a comma. See the Groupings table for the list available 

Example: 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.

Example:kpis=installs,clicks, impressions,sessions,retention_day_7

 Yes
filters

Data can be filtered using one or more filter options.

No
currency To return data using the app-specific currency set currency=preferred No
timezeone

To return data using the app-specific timezone set timezone=preferred

No
format

By default, the response data is received in CSV file format. If you prefer to get the data in JSON format append &format=json to the URI

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. Available only if cost and installs are included in the call. 
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
* Event name must be lower case

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)

Parameter Description Example Mandatory?

pid

Used for selecting the rows, which the specified media source/s are displayed in. 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

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

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

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

Parameter Description Example Mandatory?

currency

Monetary values are in the app-specific currency

currency=preferred

No

timezone

Time zone used is according to the app-specific timezone

timezone=preferred

No

For results to appear in the Master API according to Time Zone, the timezone=preferred parameter must be used.

Example calls

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 [api_token ] with your API token
  • Replace the from and to dates to the required date range
  • Change the KPIs according to your requirements
  • You can get the report using the app-specific time zone and currency by using the following: &timezone=preferred and/or &currency=preferred to the query URL
Elaborate Facebook Report

Compare 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 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
Network retention report
Compare all networks installs for users retention on day 1, 7, 15, 22, and 30 after the install 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=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 and troubleshooting

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. To get eCPI, provided the cost is available, include both installs and cost in the call. 
    • 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
  • Event names: Master API currently doesn't support event names having the forward-slash / . To overcome this limitation, avoid the user of / in event names. 

Troubleshooting

 

Message

Remark 

200 OK  
  • Symptom: No file returns
  • No token sent
401 Unauthorized The supplied API token is invalid
  • The server could not authenticate the request. The API token is either missing or invalid.
  • Make sure that the URL contains the correct API token. The API token is passed in the api_token parameter.
404 Not found
  • There is a networking problem
  • Master API is not part of your subscription plan
416 No Groupings Selected
  • The master API provides aggregate reports. These reports require KPIs according to which data is aggregated.
  • Specify the desired groupings in the groupings parameter.
403 Unrecognized date format. Check the dates and correct them 
403 From date can't be after To date. Check the dates and correct them 
403 From and To dates must have the same granularity format. Check the dates and correct them
403 No KPIs provided.  
403 Daily queries cannot contain weekly fields.  
403 Weekly results cannot be grouped by install_day. Please rephrase your query, and consider grouping by install_time instead.  
403 Weekly queries cannot contain daily fields.  
403 Our weekly retention supports up to 12 weeks.  
403 One or more of the formula's operators are not supported when not unicode.  
403 No calculated kpi name provided.  
416 Something went wrong. Please re-try to download in a minute, choose narrower time range, or contact AppsFlyer for support.
  •  Check that the date format complies with yyyy-mm-dd
  • If the KPI type is cohort, ensure that the requested KPI complies with the format:
416 The requested time range is in UTC only (prior to the timezone change)  
403 Not authorized app-ids: <app_ids>  
  • This error occurs when you make a request for data related to an app that is not listed in your dashboard.
  • Verify that the app ID you pass in the app_id parameter is the correct app ID.
  • For Android, the app ID is the package ID.

    For iOS, the app ID is the App ID rather than the bundle ID.

416 Please select authorized app-id  
416 No Groupings Selected  
416 Wrong API Fields

The field doesn't exist or is not permitted

416 Other reason

The report size exceeds 200K

Was this article helpful?