At a glance: Use URIs to get your AppsFlyer aggregate reports in CSV files.
Are you looking for Pull API raw data?
Pull API aggregate data characteristics
- Reports return as CSV files.
- Data freshness rates are the same as the equivalent report on the Export Data page and Overview dashboard page. Consider that cost can update with a delay of several hours and this depends on the partner providing the cost data.
- Filter by options available: Media source and date range.
- Additional capabilities in Pull API are:
- Ability to filter by attribution touch type
- Selectable timezone
- Pull API is suited to use by account users and BI developers;
- Account users get reports by pasting URIs in their browser. The URI templates are available in the Dashboard. Go to Integration > API access.
- BI developers get reports by embedding the URIs in scripts.
Aggregate performance reports available via Pull API
Category | UA | Retargeting* | Protect360 |
---|---|---|---|
Partners (media source) | ✓ | ✓ | ✓ |
Partners by date |
✓ | ✓ | ✓ |
Daily |
✓ | ✓ | ✓ |
Geo |
✓ | ✓ | ✓ |
Geo by date report |
✓ | ✓ | ✓ |
* For retargeting reports, add the |
Related reading:
- Descriptions and examples of aggregate reports
- Selecting the right data delivery tool for aggregated data
Terminology
Term | Description |
---|---|
Pull API |
Solution for downloading CSV reports using URIs. |
API call or call |
Sending the URI to AppsFlyer by pasting it in the browser address bar or by using scripts. |
URI |
|
Guide for account users
About URI templates
- URI templates available in the dev hub are populated with the app ID and report type.
- They have placeholders for from and to dates which you must edit.
- The portion of the URI to the right of the question mark (?) contains parameters. Each parameter begins with an ampersand (&). Parameters are used to set filters, specify additional fields to be included, currency, and timezone. For example, in aggregate reports to limit (filter by) a specific media source, use the media_source parameter:
&media_source=facebook
- To get a better understanding of Pull API, complete the tutorial that follows.
Getting your first Pull API report tutorial
Before you begin:- Ask an admin user to provide you with the Pull API token.
To download a report from dev hub:
- Go to the AppsFlyer dev hub API reference.
-
Select a report type from the left-hand menu.
For example, Raw data reports (non-organic) > Installs.
See the table below for a list of all report types. - Fill in all the required fields
- The URI template displays on the right.
- Copy the URI by clicking on the copy icon.
- Open a new tab in your browser, and paste the URI.
- Click <Enter> to send the API call.
The report downloads.
Report | Description | Refresh rate |
---|---|---|
Raw data reports (non-organic) | ||
Installs | Records non-organic installs. The record is generated when a user opens the app for the first time. |
Real-time |
In-app events | Records the events performed by users. |
Real-time |
Uninstalls | Records when a user uninstalls the app. |
Daily |
Reinstalls |
Records users who after uninstalling the app, engage with a UA media source and reinstall the app during the re-attribution window. | Real-time |
Raw data reports (organic) |
||
Organic Installs |
Records when the app is opened by a user for the first time. |
Continuous |
Organic in-app events |
Records details about events performed by users. |
Continuous |
Organic uninstalls |
Records users uninstalling the app. |
Daily |
Organic reinstalls |
Records ad revenue for users attributed to a retargeting media source during the re-engagement window. |
Daily |
Ad revenue raw data |
||
Attributed ad revenue |
Records ad revenue for users attributed to a media source. | Daily |
Organic ad revenue | Records ad revenue for users not attributed to a media source. | Daily |
Protect360 fraud | ||
Installs | Records installs identified as fraudulent and therefore not attributed to any media source. | Real-time |
Post-attribution installs | Records in-app events from fraudulent installs and therefore not attributed at all. | Real-time |
In-app events | Records in-app events identified as fraudulent by Protect360. | Daily |
Post-attribution in-app events | Records in-app events for installs identified as fraudulent after being attributed to a media source or judged fraudulent without regard to the install itself. | Daily |
Clicks | Records clicks performed by users blocked by Protect360. | Daily |
Blocked install postbacks | Records copies of postbacks sent to a media source resulting in a blocked install. | Real-time |
Postbacks | ||
Install postbacks | Records install events generated when a user opens the app for the first time. | Daily |
In-app event postbacks | Records in-app event postbacks sent to the media source. | Daily |
Retargeting in-app event postbacks | Records in-app events users performed during the re-engagement window. | Real-time |
Retargeting conversions postbacks | Records in-app events users performed during the re-engagement window. | Real-time |
Aggregate data Pull API parameters
Aggregate report URI and parameters
Aggregate URI mandatory parameters
Parameter | Description |
---|---|
api_token | API bearer authorization token. |
from |
|
to | End date. As for from |
Aggregate data optional filtering and display parameters excluding Protect360 reports
Parameter | Description |
---|---|
media_source |
Use to limit (filter) to a specific media source.
|
attribution_touch_type |
Set this parameter as shown in the example to get view-through attribution (VTA) KPIs. Example: |
currency |
Currency of revenue and cost. Aggregate Pull API reports always use the app-specific currency. |
reattr |
Get retargeting conversions data.
|
timezone |
[Default] Data returns using UTC.
Notes about selecting timezones
|
Google Ads filtered report
https://hq.appsflyer.com/export/com.greatapp/partners_report/v5?
from=2018-04-09&to=2018-05-09&media_source=googleadwords_int
Facebook filtered report
https://hq.appsflyer.com/export/com.greatapp/partners_report/v5?
from=2018-04-09&to=2018-05-09&media_source=facebook
Parameter | Description |
---|---|
URI |
|
pid |
To filter the report by a specific media source use the |
timezone |
Selects the timezone used to return data. If timezone is not sent, data is returned using UTC. Templates including the timezone parameter. Example: |
KPIs |
Protect360 parameters are the same in Pull API and Master API.
|
View-through 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 parameter.
- 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?from=yyyy-mm-dd&to=yyyy-mm-dd&attribution_touch_type=impression |
VTA and media source |
https://hq.appsflyer.com/export/{app_id}/partners_report/v5?from=yyyy-mm-dd&to=yyyy-mm-dd&attribution_touch_type=impression&media_source=example_ad_network |
Pull API for developers
Principles of implementation
Prerequisite:
Familiarize yourself with the Pull API guide for account users.
Consider:
- For each report type available, there is a template URI in the dev hub. Select a report type from the left-hand menu.
- You modify the template to get the data you need, for example, by setting date ranges and filter by parameters.
- The parameters for raw data and aggregate data reports differ and are detailed in the report sections.
Path |
|
Path parameters |
|
HTTP method |
|
Parameter | Description |
---|---|
Example URI |
|
api_token |
|
Other parameters |
Parameters differ depending |
Example
URI call example includes additional parameters:
https://hq.appsflyer.com/export/example.app.com/installs_report/v5?
from=yyyy-mm-dd
&to=yyyy-mm-dd&additional_fields=keyword_id,store_reinstall,
deeplink_url,oaid,install_app_store,contributor1_match_type,
contributor2_match_type,contributor3_match_type,match_type
Example scripts
Integrate Pull API into scripts to retrieve data.
- As needed, edit the scripts in terms of report type, date range, and filters.
- These examples use the install report.
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 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 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 = {
'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 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>';
$from = '<FROM_DATE>';
$to = '<TO_DATE>';
$query = http_build_query([
'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;
}
?>
Additional information
Traits and limitations
Trait | Comments |
---|---|
API token type required | ![]() |
Ad network access | N |
Agency access | Y |
Agency transparency | Y |
App-specific currency | Y |
App-specific timezone | Y |
Cost | Cost data is for UA campaigns only; not for retargeting or inactive campaigns (campaigns without any installs). |
Data freshness | Continuous |
Historical data | Y |
Non-organic data | Y |
Organic data | Y |
Rate limitations | |
Size limitations |
Note! Pull API for raw data support 1M rows. Aggregate data reports are limited to 200K rows. |
Campaign name changes | Pull API reports don't support campaign name changes |
API error codes and troubleshooting
Status | Code | Symptom/message | Solution |
---|---|---|---|
OK | 200 | Empty CSV file |
|
OK |
200 |
|
No API token found in the URI |
Bad request |
400 |
Raw Reports historical lookback is limited to 90 days |
Use |
Bad request |
400 |
Your API calls limit has been reached for the given report type |
- |
Unauthorized |
401 |
Supplied API token is invalid |
Ask an admin for the current token. |
Unauthorized |
401 |
Account may be suspended |
Log in to the dashboard and check the account status. |
Not found |
404 |
AppsFlyer 404 error message page displays |
|