Pull API real-time raw data and aggregate data reporting

At a glance: Use URIs to download raw data and aggregate data reports in CSV files. 

mceclip2.png

Pull API

Quick start guide - using Pull API for the first time

PullAPIURI_us-en.png
  • Pull API lets you get reports by pasting a URI link in the address bar of your browser.
  • The URI link contains the app ID, report type, report date range and an authentication token. 
  • You don't need to prepare the URI; the ready-made URI is available in the dashboard.

In the procedure that follows you will:

  • Get the ready-made URI from the dashboard. 
  • Edit the URI; replace the token and date placeholders with the required values.

Prerequisite:

To get a report using Pull API:

  1. Go to Integration > API access.
    The API window opens. 

    PullAPIChoose_us-en.png

  2. Select a report type, for example, Partners report.
  3. In the URI area, click. 
    The Copied successfully! message displays.
  4. In your browser, open a new tab, paste the URI.
  5. Edit the URI as follows:
    1. Replace the token placeholder with the Pull API token you received from the admin. For example if the token provided to you by the admin is abcdef123456789, then replace the token using the following: api_token=abcdef123456789
    2. Replace the from and to placeholders with dates. For example,
      &from=2020-01-20&to=2020-01-31
  6. To send the call,  <Enter>.
    The report downloads.
  • Pull API enables you to use URIs (browser address) to get reports having a CSV format. URIs can be used directly in the browser address bar or embedded in scripts
  • API calls can be created as described in this article.
  • Prepared calls are available in the platform, Go to Integration > API access. You need an API reporting token to use calls. 
  • Endpoints and example calls can be found in this article: Raw data, Aggregate attribution, Protect360 aggregate.
  • From time to time new fields are added to Pull API. These are never added to the default field list so as not to break your parsing and data ingestion processes. 

List of reports available

Raw data reports available 

Pull API raw data reports available (Activity date)
Conversion type Description Organic Non-Organic
Acquisition Installs 
Acquisition In-app events 
Acquisition Ad revenue raw data
Retargeting Retargeting includes re-engagements and re-attributions -
Retargeting In-app Events from re-attributions and re-engagements -
Retargeting Ad revenue raw data   
Acquisition Non-organic uninstalls  -
Validation rules Invalid installs -
Validation rules Invalid-in-app events -
Protect360 Post-attribution raw data fraud -

Aggregate reports available

Description User acquisition Retargeting Protect360

Partners (media source)

Partners by date

Daily

Geo
Geo by date
Pull API aggregate reports available (LTV)

Implementing Pull API

Pull API principles of operation

Pull API facts
API endpoint

https://hq.appsflyer.com/export/app_id/report_type/v5

  • app_id:
    • Is the app identifier as found in the AppsFlyer dashboard. Insert it exactly as it appears in the dashboard.
    • Ensure that iOS apps are prefixed with id
  • report_type is the type of report 
HTTP method GET
Authorization

An API key is included as a query parameter having the key api_token. See the example that follows in this section.

  • To get an API authentication token: In the platform, the admin must go to, your email > API Tokens.
  • Changing the AppsFlyer account admin: If the account admin changes: the API token changes. This means, that if you have Pull API URLs contained in scripts, you need to update the pull API method in the script with the updated token
Mandatory parameters
Parameter Description
api_token In example calls this is shown as: <API TOKEN HERE>. To get the token
from
  • The date range consists of a fromand to parameters. The range can be either an LTV or activity date range depending on the report type:
    • LTV date range: Aggregate data
    • Event date range: Raw data, activity dashboard
  • Format: yyyy-mm-dd, yyyy-mm-dd hh:mm, or yyyy-mm-dd hh:mm:ss Note!: The : needs to be encoded. 
  • Example: 2010-01-01 or 2010-01-01 20:15 (Hours and minutes parameters are only used in raw reports only. 
to End date. As for from

 Example call

The example is a complete call with additional parameters. In the sections that follow, examples are provided for each type of report that is available. 

GET 'https://hq.appsflyer.com/export/<APP ID HERE>/installs_report/v5?
      from=2020-01-01&to=2020-01-10&api_token=<API TOKEN HERE>&currency=preferred
  • A Pull API call is created manually, as described in this article, or you can retrieve prepared calls from the platform. To get prepared API calls, Goto Integration > API access
  • Changing from Pull API V4 to Pull API V5:
    • Raw data: The existing API (v4) is still available for use. The version does not apply any change to the file format or headers.
    • Aggregate data: In V5, performance reports that contain multiple partners, group Facebook data by campaign.
    • Performance reports that contain Facebook data only by specifying &pid=facebook  group by campaign, asset, and adgroup. 

If you manually create API links, ensure that:

  • Parameters are in lowercase
  • Don't specify the same field twice in the same link. Doing so results in an empty file.

Traits and limitations

Trait
Trait Yes  / No x Remarks 
Ad network access   
Agency access  
Agency transparency  
App-specific time zone  
App-specific currency   
Size limitations -
  • Maximum number of records per report (API call) is 200K
  • If you get a report that has exactly 200K rows, assume you are missing rows. Split the call into You can split reports into multiple calls by limiting the date and time range. 
Rate limitation

 API rate limitatons:

Organic data Available
Non-organic data Available
Data freshness Real-time  
Historical data  
Team member access
  • The admin can get the Pull API token.
  • Team members can't.

PremiumFeature.jpgRaw data

List of raw data API calls

Raw data reports dates are activity dates

Report category Report type Link example
Raw data reports Non-organic installs https://hq.appsflyer.com/export/<APP ID HERE>/installs_report/v5?api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd
  Retargeting conversions https://hq.appsflyer.com/export/<APP ID HERE>/installs_report/v5?api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd&additional_fields=install_app_store,contributor1_match_type,contributor2_match_type,contributor3_match_type,match_type,device_category,gp_referrer,gp_click_time,gp_install_begin,amazon_aid,keyword_match_type&reattr=true
 

Non-organic in-app events report

See: Filter by event name
https://hq.appsflyer.com/export/<APP ID HERE>/in_app_events_report/v5?api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd
 

Retargeting in-app events report

See: Filter by event name

https://hq.appsflyer.com/export/<APP ID HERE>/in_app_events_report/v5?api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd&additional_fields=install_app_store,contributor1_match_type,contributor2_match_type,contributor3_match_type,match_type,device_category,gp_referrer,gp_click_time,gp_install_begin,amazon_aid,keyword_match_type&reattr=true
  Non-organic uninstalls https://hq.appsflyer.com/export/<APP ID HERE>/uninstall_events_report/v5?api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd
  Organic installations  https://hq.appsflyer.com/export/<APP ID HERE}/organic_installs_report/v5?api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd
 

Organic in-app events report

See: Filter by event name

https://hq.appsflyer.com/export/<APP ID HERE>/organic_in_app_events_report/v5?api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd
Validation rules reports Invalid installs report https://hq.appsflyer.com/export/<APP ID HERE>/invalid_installs_report/v5?api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd&additional_fields=rejected_reason,rejected_reason_value
 

Invalid in-app events report

See: Filter by event name

https://hq.appsflyer.com/export/<APP ID HERE>/invalid_in_app_events_report/v5?api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd&additional_fields=rejected_reason,rejected_reason_value
Protect360 

Post-attribution raw data fraud

https://hq.appsflyer.com/export/<APP ID HERE>/detection/v5?api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd&additional_fields=install_app_store,match_type,contributor1_match_type,contributor2_match_type,contributor3_match_type,device_category,gp_referrer,gp_click_time,gp_install_begin,fraud_reason,fraud_sub_reason,fraud_reasons,install_time_tz,detection_date&detect-from=yyyy-mm-dd&detect-to=yyyy-mm-dd

Note regarding date parameters
From/to: is the install date range limited to one calendar month. 
detect-from/detect-to: is the date of the detection and is limited to the seventh day of the calendar month following the installation. 

Raw data API call parameters 

Raw data mandatory parameters
Parameter Description
api_token API Authorization token. In example calls this is shown as: <API TOKEN HERE>. 
from
  • The date range consists of a fromand to parameters. The dates relate to the activity date.
  • Format: yyyy-mm-dd, yyyy-mm-dd hh:mm, or yyyy-mm-dd hh:mm:ss Note!: The : needs to be encoded. 
  • Example: 2010-01-01 or 2010-01-01 20:15 (Hours and minutes parameters are only used in raw reports only. 
to End date. As for from
Raw data optional filtering and display parameters
Parameter Description
media_source
  • media_source: To limit (filter) the call to a specific media source.

 

event_name

Filter in-app events to include only the specified events. Multiple events can be selected using a comma-separated list of events.

Exampleevent_name=af_purchase,ftd 

reattr

Get retargeting attributions data.

  • If true, returns retargeting attribution data. 
  • If false [default], user acquisition data returns

Example:reattr=true

additional_fields

To get additional fields in addition to the default fields. 

Example: additional_fields=device_download_time,deeplink_url

currency

[Default] Revenue and cost return in USD.

  • To get revenue and cost in the app-specific currency, add currency=preferredto the call. 
  • Don't send this parameter if you want USD. 

Example: If the app-specific currency is EUR, then sending currency=preferred causes the values to return in EUR.

timezone

[Default] Data returns using UTC time zone.

  • To get data in the app-specific timezone, add timezone as shown in this section to the call: 
  •  timezone=[Joda-Time] 
  •  timezone=[Numerical value] For example: for time zone UTC+10:00 usetimezone=+10:00 Note!: The +,-, and : need to be encoded. Example: +10:00 encodes to %2B10%3A00

Using numeric value for timezone is only possible when pulling raw data reports. It doesn't work with aggregate reports like performance reports

Notes about selecting timezones

  • Joda-Time time zone format takes into account daylight saving time.
  • The Joda-Time value must be identical to the possible values in the app settings page. For example, if you wish to get data in France's time zone, check the time zone list in the app settings page, which is "Europe/Paris" for France. The timezone value in the Pull API URL should be timezone=Europe%2fParis. Pulling data in the selected time zone is only available from the date when the time zone setting was made. Any data prior to the date of the change is shown as default GMT.

Limiting date ranges by time of day

If the call results of a single day exceed 200K rows, you must split the call by using the time of day. Use the format yyyy-mm-dd hh:mm in the from and to parameters to specify the time of day. 

When specifying times of day and dates the following inclusion rules apply: 

  • from includes the value stated.
  • to: 
    • Where only the date is stated, it means up to the end of the day (midnight).  
    • If both date and time are stated, it means up to but not including the time stated. 

The inclusion principles are illustrated in the example that follows. 

For example, an app owner has up to 300K daily installs from all sources. To overcome the 200K limitation, the app owner splits the day into two calls each of 12 hours as shown in the table that follows. 

API call From  To 
First call 

from=yyyy-mm-dd

Example: 2019-12-29 means the beginning of the day.

to=yyyy-mm-dd 12:00

Example: 2019-12-29 12:00 (means up to but not including 12:00) 

Second call (Option A)

from=yyyy-mm-dd 12:00

Example: 2019-12-29 12:00

Means from 12:00, including 12:00. 

to=yyyy-mm-dd Don't specify the time of day. Example: 2019-12-29 means midnight. 

 

Exampe using option A: Period starting midday December 29, 2019 until the end of the day (midgnight) December 29, 2019.

&from=2019-12-29 12:00&to=2019-12-29
Second call (Option B) as above

to=yyyy-mm-dd+1 00:00

+1 means next day at 00:00

Example: 2019-12-30 00:00 means upto 00:00 but not including. 

Note: Option A and B provide the identical results. Use either option. 

Adding additional raw data fields

  • The fields listed here are always returned.
  • Use the additional_fields parameter to get other fields. List of fields available on the platform.
  • For example, additional_fields=device_download_time,deeplink_url
  • Ensure that you don't list the same field more than once.
  • Some example calls in the platform or in this article already include some additional fields. Add more fields if necessary. 
  • We never add fields to the default list of fields so as not to break your import and ingestion processes. 

 Example

Example call with additional fields

https://hq.appsflyer.com/export/<APP ID HERE>/installs_report/v5?
        api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd
        &additional_fields=device_download_time,deeplink_url
Default Pull API fields
Default Pull API fields
Attributed Touch Time
Install Time
Event Time
Event Name
Event Value
Event Revenue
Event Revenue Currency
Event Revenue USD
Event Source
Is Receipt Validated
Partner
Media Source
Channel
Keywords
Campaign
Campaign ID
Adset
Adset ID
Ad
Ad ID
Ad Type
Site ID
Sub Site ID
Sub Param 1
Sub Param 2
Sub Param 3
Sub Param 4
Sub Param 5
Cost Model
Cost Value
Cost Currency
Contributor 1 Partner
Contributor 1 Media Source
Contributor 1 Campaign
Contributor 1 Touch Type
Contributor 1 Touch Time
Contributor 2 Partner
Contributor 2 Media Source
Contributor 2 Campaign
Contributor 2 Touch Type
Contributor 2 Touch Time
Contributor 3 Partner
Contributor 3 Media Source
Contributor 3 Campaign
Contributor 3 Touch Type
Contributor 3 Touch Time
Region
Country Code
State
City
Postal Code
DMA
IP
WIFI
Operator
Carrier
Language
AppsFlyer ID
Advertising ID
IDFA
Android ID
Customer User ID
IMEI
IDFV
Platform
Device Type
OS Version
App Version
SDK Version
App ID
App Name
Bundle ID
Is Retargeting
Retargeting Conversion Type
Attribution Lookback
Reengagement Window
Is Primary Attribution
User Agent
HTTP Referrer
Original URL

Aggregate

Aggregate reports are LTV based. Report descriptions

List of aggregate data API calls

Report category Report name Link example
Performance reports

Partners (media source)

(LTV)

https://hq.appsflyer.com/export//partners_report/v5?api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd
  Partners by date
(LTV)
https://hq.appsflyer.com/export//partners_by_date_report/v5?api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd
 

Daily

(LTV)

https://hq.appsflyer.com/export//daily_report/v5?api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd
  Geo
(LTV)
https://hq.appsflyer.com/export//geo_report/v5?api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd
  Geo by date 
(LTV)
https://hq.appsflyer.com/export//geo_by_date_report/v5?api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd
Retargeting Reports Partners
(LTV)
https://hq.appsflyer.com/export//partners_report/v5?api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd&reattr=true
 

Partners by date

(LTV)

https://hq.appsflyer.com/export//partners_by_date_report/v5?api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd&reattr=true
 

Daily

(LTV)

https://hq.appsflyer.com/export//daily_report/v5?api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd&reattr=true
 

Geo

(LTV)

https://hq.appsflyer.com/export//geo_report/v5?api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd&reattr=true
 

Geo By Date 

(LTV)

https://hq.appsflyer.com/export//geo_by_date_report/v5?api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd&reattr=true

Aggregate API parameters

Aggregate data mandatory parameters
Parameter Description
api_token API Authorization token. In example calls this is shown as: <API TOKEN HERE>. https://support.appsflyer.com/hc/en-us/articles/360004562377 
from
  • The date range consists of a fromand to parameter. The range is LTV date range: Aggregate data
  • Format: yyyy-mm-dd, yyyy-mm-dd hh:mm, or yyyy-mm-dd hh:mm:ss Note!: The : needs to be encoded. 
  • Example: 2010-01-01 or 2010-01-01 20:15 (Hours and minutes parameters are only used in raw reports only. 
to End date. As for from
Aggregate data optional filtering and display parameters
Parameter Description
media_source

media_source: To limit (filter) the call to a specific media source.

attributed_touch_type

Set this parameter as shown in the example to get view-through attribution (VTA) KPIs. 

Example:  attributed_touch_type=impresssion

reattr

Get retargeting attributions data.

  • If true, returns retargeting attribution data. 
  • If false [default], user acquisition data returns

Example:reattr=true

currency

[Default] Revenue and cost return in USD.

  • To get revenue and cost in the app-specific currency, add currency=preferredto the call. 
  • Don't send this parameter if you want USD. 

Example: If the app-specific currency is EUR, then sending currency=preferred causes the values to return in EUR.

timezone

[Default] Data returns using UTC time zone.

  • To get data in the app-specific timezone, add timezone as shown in this section to the call: 
  •  timezone=[Joda-Time] 

Notes about selecting timezones

  • Joda-Time time zone format takes into account daylight saving time.
  • The Joda-Time value must be identical to the possible values in the app settings page. For example, if you wish to get data in France's time zone, check the time zone list in the app settings page, which is "Europe/Paris" for France. The timezone value in the Pull API URL should be timezone=Europe%2fParis. Pulling data in the selected time zone is only available from the date when the time zone setting was made. Any data prior to the date of the change, is shown as default GMT.

 

 Important!

The date range and media source filters can affect which event columns appear in the report.

If you consume the data and push it into your BI systems, make sure to account for possible differences in the event columns that appear in the report.

View-though attribution (VTA) KPIs

  • To get the VTA KPIs add the parameter attribution_touch_type=impression to the Pull API aggregate report URI as detailed in the example.
  • You can use the parameter with any of the aggregate reports available. Just copy the URI from the user interface, and append the &attribution_touch_type=impression
  • You can also add the &media_source parameter to limit the report to a specific media source as depicted in the example that follows.
  • Some VTA KPIs, like clicks, impressions, and cost APIs, don't have values associated with them and display the value N/A instead. 
Example Example URI
VTA only  https://hq.appsflyer.com/export/{app_id}/partners_report/v5?api_token={API token}&from=yyyy-mm-dd&to=yyyy-mm-dd>&attributed_touch_type=impression

VTA and media source

https://hq.appsflyer.com/export/{app_id}/partners_report/v5?api_token={API token}&from=yyyy-mm-dd&to=yyyy-mm-dd&attributed_touch_type=impression&media_source=example_add_network

List of Protect360 calls 

To get Protect360 aggregate reports, use the Pull API URIs available in the Integration >API access page of the Dashboard.

The Protect360 aggregate advanced detection reports are:

  • Partners report
  • Partners daily report
  • Geo report
  • Geo daily report
  • Partners campaign report

List of parameters (KPIs) and descriptions 

 

Protect360 API parameters

Protect360 mandatory parameters
parameter Description
api_token API Authorization token. In example calls this is shown as: <API TOKEN HERE>.
from
  • The date range consists of a fromand to parameter. The range is the LTV range, being the install date. 
  • Format: yyyy-mm-dd
to End date. As for from
Protect360 optional filtering and display parameter
parameter Description
pid

To filter the report by a specific media source use the pidparameter. For example, to get the data of abc_net, pid=abc_net.

currency

[Default] Revenue and cost return in USD.

  • To get revenue and cost in the app-specific currency, add currency=preferredto the call. 
  • Don't send this parameter if you want USD. 

Example: If the app-specific currency is EUR, then sending currency=preferred causes the values to return in EUR.

timezone

[Default] Data returns using UTC time zone.

  • To get data in the app-specific timezone, add timezone=preferred

 Selecting KPIs

Additional information

Example scripts

Pull API can be integrated in scripts to get the data for you. The examples contain scripts used to retrieve data using the API.

  •  The examples, use the install report.
  • Edit the scripts to fit your requirements in terms of report type, date range, and filters. 
JavaNode JSPythonC#PHP
import okhttp3.*;

import java.io.BufferedWriter;
import java.io.FileWriter;

import java.util.concurrent.TimeUnit;

public class PullApi {
  public static void main(String[] args){

    String appID = "<APP_ID>";
    String reportType = "<REPORT_TYPE>";
    String apiToken = "<API_TOKEN>";
    String from = "<FROM_DATE>";
    String to = "<TO_DATE>";
    String requestUrl = "https://hq.appsflyer.com/export/" + appID + "/" + reportType + "/v5?api_token=" + apiToken + "&from=" + from + "&to=" + to;

    OkHttpClient client = new OkHttpClient.Builder()
        .connectTimeout(30, TimeUnit.SECONDS)
        .readTimeout(30, TimeUnit.SECONDS)

        .build();

    Request request = new Request.Builder()
        .url(requestUrl)
        .addHeader("Accept", "text/csv")
        .build();

    try {
      Response response = client.newCall(request).execute();

      if(response.code() != 200) {
        if(response.code() == 404) {
          System.out.println("There is a problem with the request URL. Please make sure it is correct");
        }
        else {
          assert response.body() != null;
          System.out.println("There was a problem retrieving the data: " + response.body().string());
        }
      } else {
        assert response.body() != null;
        String data = response.body().string();
        BufferedWriter writer;

        writer = new BufferedWriter(new FileWriter(appID + "-" + reportType + "-" + from + "-to-" + to + ".csv"));
        writer.write("");
        writer.write(data);
        writer.close();
      }
      System.exit(0);
    } catch (Exception e) {
      e.printStackTrace();
      System.exit(1);
    }
  }
}

API error codes and troubleshooting

Error codes and solutions
Symptom  Return code Solution 
An empty CSV file returns 200 Anadditional_fields appears in the call more than once.
 The supplied API token is invalid 

401

  • The server could not authenticate the request.
  • Troubleshooting: 
    • Make sure that the URL contains the correct API token.
    • The API token is passed in the api_token parameter.
    • If the admin changed recently, the token automatically changes. Get a new token from the admin.
Unauthorized

401

The account may be suspended. Login to the dashboard and check the account status. 
 The server could not comply with the request since it is either malformed or otherwise incorrect.

400

  • API querying date range is limited to the past 3 months.
  • Limit the date range to 3 months or less using the to and from parameters.
Was this article helpful?