Master API—user acquisition metrics via API

Premium

For:

Marketers Developers

Last update: May 28, 2023 09:34

At a glance: Get selected LTV, activity, retention, cohort, and Protect360 campaign performance KPIs by API, in CSV or JSON format. Select 1 or more apps.

Master API—user acquisition metrics via API

Master API:

Lets you get selected LTV, activity, retention, cohort, and Protect360 campaign performance KPIs. The KPIs available are the equivalent KPIs of those found in the Overview, Activity, Retention, Cohort, and Protect360 dashboards.
Is calculated daily. The updated data is available to you within 24-48 hours, depending on your app-specific timezone.
Is the infrastructure upon which the AppsFlyer pivot table is built.

To use Master API, you define the data that you want to view (similar to the implementation of the Pull API). The result returns as a CSV or JSON file.

To use Master API:

Get the API token. An admin needs to retrieve the token.
Give your developer the API token to be used in the authentication header.
Give your developers the parameters to input when they make the API call, as described in the sections that follow. The parameters determine what the report focuses on, how it's organized, and provide a reporting timeframe.
Tell your developer to follow their Master API instructions in the developer hub.

API parameters

Parameter	Value	Mandatory
app_id	App identifier, as found in AppsFlyer. Insert the app ID exactly as found in AppsFlyer Prefix iOS apps with id Use all app IDs to query for all your apps	Yes
from	Lower-bound of the LTV attribution date range. Format: String yyyy-mm-dd Example: `from: 2020-01-02`	Yes
to	Upper-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: 2021-01-01, to: 2021-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
Timezone	To return data using the app-specific timezone set timezone=preferred. See localization rules	No
Format	By default, the response data is received in CSV file format. If you prefer to get the data in JSON format, select `format=json`.	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	No	No
af_ad	Ad	Yes	Yes	Yes	No	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	No	No
af_ad_id	Ad ID	Yes	No	Yes	No	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
* In the context of Activity KPIs, regard install time as event time.

KPIs

KPIs are the metrics used for gaining insights into the behavior of your app. The KPIs are grouped by type in the tabs that follow.

Lifetime Value - Aggregate Events segmented 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. See limitations.
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_name]	Number of event occurrences
unique_users_[event_name]	Number of unique users who performed the event
sales_in_usd_[event_name]	Revenue reported as part of the reported events

Retention is a measure of how many existing users are active in your app.

Note:

The maximum retention day number is 30 days post-install, where day 0 is the install day. This means that value [x] cannot exceed 30.
If you request retention_day_1, before the data for that day is available then the metric that returns relates to users installing on the previous day. For example, on Jan 2, you request retention_day_1 for users who installed on Jan 1. Because the metric isn't yet available, the metric that returns relates to users who installed on Dec 31.

KPI	Description
retention_day_[x]	Number of retained users at day X
retention_rate_day_[x]	Number of retained users at day X out of installing users

App activity occurring during a selected date range.

KPI	Description
activity_average_dau	Average daily active users (DAU) within the selected time frame
activity_average_mau	Average monthly active users within the selected time frame (one MAU day represents the unique users in the preceding 30 days)
activity_average_dau_mau_rate	Average DAU/MAU rate
activity_average_arpdau	Average revenue per daily active user - the average revenue of a given day out of all unique users
activity_sessions	Number of sessions performed within the selected time frame
activity_revenue	Revenue reported within the selected time frame
activity_event_counter_[event_name]	Number of events generated by users within the selected time frame
activity_sales_in_usd_[event_name]	Revenue reported as part of the reported events within the selected time frame
activity_average_unique_users_[event_name]	Average unique users performing a given event within the selected time frame

AppsFlyer Cohorts provide advertisers with the ability to view and compare different metrics for multiple cohorts over different time frames.

Note:

Rounding errors: Cohort per user KPIs are calculated using four decimal places. This means that if the calculated value per user is < 0.0001 then this shows as 0. For example, the number of users is 100,000, and total revenue is $9. The revenue per user is 9/100000=0.00009. As 0.00009<0.0001 the value shown will be 0.
Cohort days: The maximum cohort day number is 90 days post-install where day 0 is the install day. The cohort day value [x] must be in the range of 1-90. Note: cohort_day_0 isn't supported in Mater API, even though it's supported in the Cohort dashboard.
Master API vs. Cohort API and Cohort dashboard: Results may differ due to different handling of reinstalls and timing issues.

Sessions

KPI

Description

cohort_day_[x]_total_sessions_per_user

Cohort Day x - Cumulative sessions per user up to day x (including day x)

cohort_day_[x]_sessions_per_user

Cohort Day x - Sessions on day x only from the cohort

cohort_[x]_days_total_sessions_per_user

Replaces specifying KPIs Cohort_day_1_total_sessions_per_user to Cohort_day_x_total_sessions_per_user on the URL.

For example: cohort_3_days_total_sessions_per_user on the URL produces 3 report columns:
Cohort_day_1_total_sessions_per_user+ Cohort_day_2_total_sessions_per_user+Cohort_day_3_total_sessions_per_user

Revenue

KPI	Description
cohort_day_[x]_total_revenue_per_user	Cohort Day x - Cumulative revenue per user up to day x (including day x)
cohort_day_[x]_revenue_per_user	Cohort Day x - ARPU received on day x only from the cohort
cohort_[x]_days_total_revenue_per_user	Replaces specifying KPIs Cohort_day_1_total_revenue_per_user to Cohort_day_x_total_revenue_per_user. For example: cohort_3_days_total_revenue_per_user on the URL produces 3 report columns: Cohort_day_1_total_revenue_per_user+ Cohort_day_2_total_revenue_per_user+Cohort_day_3_total_revenue_per_user
cohort_day_[x]_total_event_[eventname]_revenue_per_user	Cohort Day x accumulative revenue per user according to specific in-app event
cohort_day_[x]_event_[eventname]_revenue_per_user	Cohort Day x revenue per user according to specific in-app event

Events

KPI

Description

cohort_day_[x]_total_event_[eventname]_per_user

Cohort Day x - Cumulative events per user up to day x (including day x)

cohort_day_[x]_event_[eventname]_per_user

Cohort Day x - Events received on day x only from the cohort

cohort_[x]_days_total_event_[eventname]_per_user

Replaces specifying KPIs events to Cohort_day_x_total_events_per_user.

For example: cohort_3_days_total_events_per_user on the URL produces 3 report columns:
Cohort_day_1_total_events_per_user+ Cohort_day_2_total_events_per_user+Cohort_day_3_total_events_per_user

Protect360 KPIs

Description	KPI
Installs
Total	protect360_total_installs
Blocked	blocked_installs
Blocked %	blocked_installs_rate
Post-attribution	post_attribution_installs
Post-attribution %	post_attribution_installs_rate
Total fraudulent installs	total_fraudulent_installs
Fraudulent installs %	fraudulent_installs_rate
Fake installs
Real-time block	real_time_fake_installs
Post-attribution fraud	post_attribution_fake_installs
Hijacked installs
Real-time block	real_time_hijacked_installs
Post-attribution fraud	post_attribution_installs_hijacked_installs
Validation rules
Blocked installs	validation_rules_blocked_installs
Blocked attribution	validation_rules_blocked_attribution
Fake installs block breakdown
Blocked site ID blacklist	blocked_installs_siteid_blacklist
Post-attribution site ID blacklist	post_attribution_installs_siteid_blacklist
Blocked bots	blocked_installs_bots
Post-attribution bots	post_attribution_installs_bots
Blocked behavioral anomalies	blocked_installs_behavioral_anomalies
Post-attribution behavioral anomalies	post_attribution_installs_behavioral_anomalies
Blocked install validation	blocked_installs_install_validation
Hijacked installs block breakdown
Blocked install hijacking	blocked_installs_install_hijacking
Post-attribution install hijacking	post_attribution_installs_installs_hijacking
Blocked CTIT anomalies	blocked_installs_ctit_anomalies
Post-attribution CTIT anomalies	post_attribution_installs_ctit_anomalies
Blocked click flooding	blocked_installs_click_flood
Post-attribution click flooding	post_attribution_installs_click_flood
Clicks
Total	protect360_total_clicks
Blocked	blocked_clicks
%	blocked_clicks_rate
In-App Events
Total	protect360_total_in_apps
Blocked	blocked_in-app-events
%	blocked_in-app-events_rate
Device farm indicators - new devices
Installs	install_fraud_new_devices_total
Installs %	install_fraud_new_devices_total_installs_rate
Loyal user %	install_fraud_new_devices_total_loyal_user_rate
Device farm indicators - LAT devices
Installs	install_fraud_lat_devices_total
Installs %	install_fraud_lat_devices_total_installs_rate
Loyal user %	install_fraud_lat_devices_total_loyal_user_rate
Click flooding indicators
Conversion rate	conversion_rate
Click flooding indicators - CTIT
Over 60 minutes	click_flood_over_1_hour_rate
Over 5 hours	click_flood_over_5_hours_rate

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 KPI objects in the calculated KPI formulas. Each calculation KPI object includes a key and a value. The key is the name you give the KPI and the value is the KPI formula.

Standard arithmetic operators are supported: addition (+) encoded as %2b, subtraction (-), multiplication (*), division (/) encoded as %2f.

Calculated KPI field keys 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, in which the specified media source/s are displayed. 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

Localization

Local currency and app-specific timezone are set on the app settings page. Master API data can extract the data using either the system's default currency and timezone or using the app-specific timezone and currency.

The following applies:

Using the app-specific timezone/currency is supported only if all apps have the same timezone/currency. Otherwise, UTC and USD are used. Timezone and currency are separate. Meaning that if the currency of all apps is the same but the timezones aren't, then you can use the app-specific currency but not the app-specific timezone.
If the preferred timezone was changed in the dashboard within the requested time range, the generated report contains values starting from the most recent timezone 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 timezone.

Parameter	Description	Example	Mandatory?
currency	Monetary values are in the app-specific currency	currency=preferred	No
timezone	Timezone used is according to the app-specific timezone	timezone=preferred	No

Additional information

Traits and limitations

Trait	Remarks
Cost data	Availability of different cost dimensions meaning adset, ad, geo, channel, and site ID is ad network dependent. To get eCPI: If the cost data 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, Meta ads doesn’t support grouping by Geo and Channel in the same call. Grouping by either of them separately is supported. Campaigns that have cost data, but no installs data in the recent past (approx. 7 days), are not available via Master API.
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 returns N/A.
Maximum rows per report	200K
Event names	Master API currently doesn't support event names that include a forward-slash `/` . To overcome this limitation, avoid the user of `/` in event names.
Processing time	Selecting more than one app increases the processing time and the response may take longer.
Date range	Timeframe granularity is daily.
Agencies	Master API not available
Ad networks	Master API not available
Historical data	LTV data: 5 years Cohort data (daily cohort): 2 years Activity data: 3 years