Pull API: Pulling Reports Using AppsFlyer Pull APIs

Raw Data reports provide all data for installs and in-app events.

API Parameters - Required

api_token

Is the user's external API Authorization Key: "{Account owner API Key should be used}"

from

Report start date in the format of "yyyy-mm-dd" or "yyyy-mm-dd hh:mm". For example: 2010-01-01 or 2010-01-01%2000%3A15 - (The hours parameter is for raw reports only).

to

Report end date. Same format as from

API Filtering Parameters - Optional

Filter by Media Source

Filtering the reports to list only a specific media source is available by adding both the category and media source parameters to the request URL:

category

To get Facebook data set category=facebook on the URL. To get Twitter data set category=twitter on the URL. For any other specific media source set category=standard

media_source

Supply the name of a single media source (media_source=[SOURCE_NAME]) as it appears on AppsFlyer's dashboard.

https://hq.appsflyer.com/export/com.greatapp/installs_report/v5?api_token=xxxx
&from=2018-04-09&to=2018-05-09&category=standard&media_source=googleadwords_int

https://hq.appsflyer.com/export/com.greatapp/installs_report/v5?api_token=xxxx
&from=2018-04-09&to=2018-05-09&category=facebook&media_source=facebook

Filter by Event name

Filter the raw in-app events report data to include only a specific event, by using the event_name parameter. To filter multiple events use a comma separated list of events.

For example: event_name=af_purchase,ftd

For Retargeting Exports

Use reattr=true to get results attributed to retargeting campaigns.

Additional Fields

Through Pull API you can add some fields, that complete the picture for raw data installs and in-app events in some cases.

To add new fields add "&additional_fields=" to the attribution link, followed by the comma-separated list of additional fields. See the Pull API examples below.

The result is a CSV report with added columns, that contain information when relevant.

Time Zone and Currency

timezone (optional)

You can get the Pull API raw data in ANY valid time zone:

1. Add &timezone=[Joda-Time] in the Pull API link to receive the report in the preferred timezone (see note below)
2. Add &timezone=[Numerical value] in the Pull API link to receive the report in the specified numerical timezone. For example: for time zone UTC+10:00 add on the link &timezone=%2B10:00
   Using numeric value for timezone is only possible when pulling raw data reports. It doesn't work with aggregate reports like performance reports.
3. Otherwise the data is received in the default UTC time zone.

currency (optional)

Is used to receive the Revenue and Cost data in your selected currency, rather than in USD, which is the default option. This is set by the account admin.

To receive the data in your preferred currency, please add the following to your request link: &currency=preferred

is used to receive Revenue and Cost data in your selected currency.

API Policy and Usage Limitations

AppsFlyer's API Policy ensures high quality of service to the users of pull API by limiting the total number of daily requests and preventing abuse of the service.

See details about the API policy for aggregated data via Pull API and for raw data via Pull API.

The maximum number of records per report is 200K. If you get a report that has 200K rows then you have some results that were left out.

API Security

All Pull API links use secure crypted https connections.

For more details go here.

Pull API Link Examples

API Version (V5)

• Unchanged:

  • The existing API (v4) is still available for use

  • The version does not apply any change to the file format or headers

Performance Reports provide details of the effectiveness of advertising campaigns.

API Parameters - Required

api_token

Is the user's external API Authorization Key: "{Account owner API Key should be used}". The API token is displayed ONLY to the account owner

API Filtering Parameters - Optional

Filter by media source

Filtering the reports to list only a specific media source is available by adding both the category and media source parameters to the request URL:

category

To get Facebook data set category=facebook on the URL. For any other specific media source set category=standard

media_source

Supply the name of a single media source (media_source=[SOURCE_NAME]) as it appears on AppsFlyer's dashboard.

https://hq.appsflyer.com/export/com.greatapp/partners_report/v5?api_token=xxxx
&from=2018-04-09&to=2018-05-09&category=standard&media_source=googleadwords_int

https://hq.appsflyer.com/export/com.greatapp/partners_report/v5?api_token=xxxx
&from=2018-04-09&to=2018-05-09&category=facebook&media_source=facebook

Time Zone and Currency

timezone (optional)

You can get the aggregated data via Pull API in either UTC or the app's preferred time zone, which is set in the App Settings page:

1. Add &timezone=[selected Joda-Time] in the Pull API link to receive the report in the app's preferred timezone (see note below)

2. Otherwise the data is received in the default UTC time zone.

currency (optional)

Is used to receive the Revenue and Cost data in your selected currency, rather than in USD, which is the default option. This is set by the account admin.

currency=preferred

is used to receive Revenue and Cost data in your selected currency.

API Policy

AppsFlyer's API Policy ensures high quality of service to the users of pull API by limiting the total number of daily requests and preventing abuse of the service.

The maximum number of records per report is 200K. If you get a report that has 200K rows then you have some results that were left out.

API Security

All Pull API links use secure crypted https connections.

For more details go here.

Pull API Link Examples

API Version (V5)

• Changes:

  • In Version (v5) performance reports that contain multiple partners, group Facebook data by campaign only. Performance reports that contain Facebook data only (by specifying &category=facebook) group data by campaign and ad group.

  • Export data page for aggregated reports uses the API version (v5)

• Unchanged:

  • The existing API (v4) is still available for use

  • The version does not apply any change to the file format or headers

P360 aggregated data as appears in the advanced detection table in the dashboard.

API Parameters - Required

api_token

Is the user's external API Authorization Key: "{Account owner API Key should be used}"

from

Report start date in the format of "yyyy-mm-dd" or "yyyy-mm-dd hh:mm". For example: 2010-01-01 or 2010-01-01%2000%3A15 - (The hours parameter is for raw reports only).

to

Report end date. Same format as from

KPIs - Required

Protect360 parameters are the same in Pull API and Master API. 

For the list of available KPIs and their descriptions, go here.

API Filtering Parameters - Optional

Filter by media source

Filtering the reports to list only a specific media source is available by adding:
pid=media source name.

Time Zone and Currency

timezone (optional)

You can get the P360 aggregated data via Pull API in either UTC or the app's preferred time zone, which is set in the App Settings page:

1. Add &timezone=preferred in the Pull API link to receive the report in the app's preferred timezone

2. Otherwise the data is received in the default UTC time zone.

currency (optional)

Is used to receive the Revenue and Cost data in your selected currency, rather than in USD, which is the default option. This is set by the account admin.

currency=preferred

is used to receive Revenue and Cost data in your selected currency.

API Security

All Pull API links use secure crypted https connections.

For more details go here.

Pull API Link Examples

API Version (V5)

• Changes:

  • In Version (v5) performance reports that contain multiple partners, group Facebook data by campaign only. Performance reports that contain Facebook data only (by specifying &category=facebook) group data by campaign and ad group.

  • Export data page for aggregated reports uses the API version (v5)

• Unchanged:

  • The existing API (v4) is still available for use

  • The version does not apply any change to the file format or headers

Scripts to Retrieve Data from Pull API

Often times it is more convenient to setup automated scripts to retrieve data periodically.

Below you can find scripts to retrieve data from pull API. The sample scripts pull data from the install report. Edit the scripts to fit your requirements in terms of what report and what data you wish to retrieve.

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);
    }
  }
}

request = require('request');
const fs = require('fs');

const appID = '<APP_ID>';
const reportType = '<REPORT_TYPE>';
const apiToken = '<API_TOKEN>';
const from = '<FROM_DATA>';
const to = '<T0_DATE>';
const requestUrl = `https://hq.appsflyer.com/export/${appID}/${reportType}/v5?api_token=${apiToken}&from=${from}&to=${to}`;

request(requestUrl, (error, response, body) => {
  if (error) {
    console.log('There was a problem retrieving data:', error);
  }
  else if (response.statusCode != 200) {
    if (response.statusCode === 404) {
      console.log('There is a problem with the request URL. Make sure that it is correct');
    } else {
      console.log('There was a problem retrieving data:', response.body);
    }
  } else {
    fs.writeFile(`${appID}-${reportType}-${from}-to-${to}.csv`, response.body, (err) => {
      if (err) {
        console.log('There was a problem writing to file: ', err);
      } else {
        console.log('File was saved');
      }
    });
  }
  
});

import requests

app_id = '<APP_ID>'
report_type = '<REPORT_TYPE>'

params = {
  'api_token': '<API_TOKEN>',
  'from': 'FROM_DATE',
  'to': 'TO_DATE'
}

request_url = 'https://hq.appsflyer.com/export/{}/{}/v5'.format(app_id, report_type)

res = requests.request('GET', request_url, params=params)

if res.status_code != 200:
  if res.status_code == 404:
    print('There is a problem with the request URL. Make sure that it is correct')
  else:
    print('There was a problem retrieving data: ', res.text)
else:
  f = open('{}-{}-{}-to-{}.csv'.format(app_id, report_type, params['from'], params['to']), 'w', newline='', encoding="utf-8")
  f.write(res.text)
  f.close()

using System;
using RestSharp;
using System.Text;
using System.Net;
using System.IO;
namespace Pull_API
{
  class PullAPi
  {
    static void Main(string[] args)
    {
      var appID = "<APP_ID>";
      var reportType = "<REPORT_TYPE>";
      var apiToken = "<API_TOKEN>";
      var from = "<FROM_DATE>";
      var to = "<TO_DATE>";

      var requestUrl = "https://hq.appsflyer.com/export/" + appID + "/" + reportType + "/v5?api_token=" + apiToken + "&from=" + from + "&to=" + to;
      
      var client = new RestClient(requestUrl);
      var request = new RestRequest(Method.GET);
      request.AddHeader("Accept", "text/csv; charset=UTF-8");

      IRestResponse response = client.Execute(request);
      HttpStatusCode statusCode = response.StatusCode;
      int numericStatusCode = (int)statusCode;

      if(numericStatusCode != 200){

        if(numericStatusCode == 404){
          Console.WriteLine("There is a problem with the request URL. Make sure that it is correct.");
        } else {
          Console.WriteLine("There was a problem retrieving data: " + response.Content); 
        }
      } else {
        System.IO.File.WriteAllText(@"" + appID + "-" + reportType + "-" + from + "-to-" + to + ".csv", response.Content);
        Console.WriteLine("Data retrieved succesfully"); 
      }
    }
  }
}

<?

$appID = '<APP_ID>';
$reportType = '<REPORT_TYPE>';
$apiToken = '<API_TOKEN>';
$from = '<FROM_DATE>';
$to = '<TO_DATE>';
$query = http_build_query([
'api_token' => $apiToken,
'from' => $from,
'to' => $to
]);
$requestUrl = 'https://hq.appsflyer.com/export/' . $appID . '/' . $reportType . '/v5?'.$query;
$report = $appID . '-' . $report . '-' . $from . '-to-' . $to; 

$curl = curl_init($requestUrl);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_ENCODING, "");
curl_setopt($curl, CURLOPT_NOSIGNAL, true);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($curl, CURLOPT_MAXREDIRS, 10);
curl_setopt($curl, CURLOPT_FAILONERROR, true);
curl_setopt($curl, CURLOPT_TIMEOUT, 100);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($curl, CURLOPT_HTTPHEADER, array(
 "cache-control: no-cache",
 "Accept: text/csv; charset=UTF-8"
));


$response = curl_exec($curl);
$info = curl_getinfo($curl);
$err = curl_error($curl);
curl_close($curl);

var_dump($response);
if ($err) {
 echo $info['http_code']; 
 echo "cURL Error #: " . $err . '. ';
 if ($info['http_code'] == 404) {
  echo 'There is a problem with the request URL. Make sure that it is correct';
 } 
 if ($info['http_code'] == 401) {
  echo 'There was a problem retrieving data: authentication failed.';
 }
 
 echo PHP_EOL;

} else {
 $fp = fopen($report, 'w+');
 fwrite($fp, $response);
 fclose($fp);
 echo $response;
}
?>

API Errors and Troubleshooting

This section discusses common API erros and how to handle them.