Master API—user acquisition metrics via API

Premium

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:

  1. AppsFlyerAdmin_us-en.pngGet the API token. An admin needs to retrieve the token.
  2. Give your developer the API token to be used in the authentication header.
  3. 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.
  4. Tell your developer to follow their Master API instructions in the developer hub.
  5. 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 sections that follow.

    LTV

    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

    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

    Activity

    App activity occurring during a selected date range. Note: Activity KPIs include unified data (UA and retargeting together).

    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

    Cohort

    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

    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
Retargeting
  • Not supported.
  • Exception: Activity KPIs for traffic from after February 1, 2025 include unified data (UA and retargeting together).