At a glance: Use URIs to get your raw data reports in CSV files.
Pull API raw data characteristics
- Descriptions of raw data report content.
- Reports return as CSV files.
- The filter by options are: Media source, date range, in-app event name, and geo.
- Selectable timezone and currency.
- Pull API is suited for account users and BI developers:
- Account users get reports by pasting URIs in their browser. The URI is made in the dev hub.
- Pull API for BI developers get reports by embedding URIs in scripts.
- Rate limitation: A quota mechanism limits the number of reports that can be generated per day.
Related reading: Selecting the right data delivery tool/reporting API
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 the from/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 and specify additional fields to be included, currency, and timezone. For example, in raw data 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.
- Postback URIs aren't available via the dashboard. Postback URIs in a spreadsheet.
Getting your first Pull API report tutorial
The dev hub allows you easily input your custom data and test it out by downloading a report.
Before you begin:- Ask an admin user to provide you with the Pull API token available in the dashboard.
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 |
Raw data Pull API parameters
URI parameters raw data
Raw data mandatory parameters
Parameter | Description |
---|---|
api_token | API bearer authorization token. |
from |
|
to | End date. As for from |
Raw data optional parameters
Parameter | Description |
---|---|
media_source |
|
maximum_rows |
Maximum number of rows returned by a single API call.
|
event_name |
Filter in-app events by specified events. Select multiple events by using a comma-separated list. Example: |
reattr |
Set retargeting attribution data.
|
additional_fields |
To get additional fields in addition to the default fields. Example: |
currency |
Currency of the revenue and cost
Example: If the app-specific currency is EUR, by sending |
timezone |
[Default] Data returns using UTC.
|
geo |
Filter the data by country code. Limitation: You can set only one country code filter per API call. Example: |
Protect 360
Time range by date and time
If the results exceed the maximum, split the report using hours and minutes. Apply the following:
- from/to: yyyy-mm-dd hh:mm
- from:
- Date only = from the beginning (00:00) of the chosen date
- Date and time = from and including 00:00
- Parameter to:
- Date only = up to the end (24:00) of the chosen day
- Date and time = up to, but not including, the shown time
Example: An app owner has 1300K daily installs from all sources. To overcome the 1M row limit, the app owner splits the day into two 12-hour URI calls. See the following table for options.
API call | From | To |
---|---|---|
First API call |
from=yyyy-mm-dd Example:
|
to=yyyy-mm-dd 12:00 Example:
|
Option A: Second API call
Example:
|
from=yyyy-mm-dd 12:00 Example:
|
to=yyyy-mm-dd Example:
|
Option B: Second API call |
from=yyyy-mm-dd 12:00 Example:
|
to=yyyy-mm-dd+1 00:00 +1 = next day at 00:00 Example:
|
Note! Use option A or B as they have the same results. |
Additional fields
Report fields are not added to the default list of fields so that new fields don't impact your import and ingestion processes. Use the additional_fields
parameter to get non-default fields.
- List a field only once.
- See the list of available fields.
- Some URI examples include additional fields. If necessary, add more fields.
- Example:
additional_fields=device_download_time,deeplink_url
- Results are always returned for the fields listed in the table below.
Example
URI call example with additional fields:
https://hq1.appsflyer.com/api/raw-data/export/app/<APP ID HERE>/installs_report/v5?
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 |
Pull API for developers
To implement Pull API raw data using scripts consult the Pull API aggregate data article.
Additional information
Migrate from API V4 to V5
Raw data: On December 1, 2021, the V4 API will be sunset and removed from the platform. You must stop using V4 and migrate to V5 before this date.
Migrating from API V4 to V5
In migrating from V4 to V5 consider that V5 has a set of default fields that always return and optional addtional fields which you must be explicitly added to your Pull API call. Adjust your API calls to get the fields you require. AppsFlyer provides a template consisting of some additional fields in the user interface. You should edit the template to meet your needs. See get API template in the user interface.
Traits and limitations
Trait | Comments |
---|---|
API token type required | ![]() |
Ad network access | No |
Agency access | Yes |
Agency transparency | Yes |
App-specific currency | Yes |
App-specific timezone | Yes |
Data freshness |
|
Historical data | Yes. According to retention and rate limitation policies. |
Non-organic data | Yes |
Organic data | Yes |
Rate limitation |
API limitations for raw data. |
Size limitations |
|
API error codes and troubleshooting
Status | Code | Symptom/message | Solution |
---|---|---|---|
The report doesn't contain the data expected according to the selected time range or there is a discrepancy between the raw data report and aggregated data report. |
Verify that you have set the |
||
OK | 200 | Empty CSV file |
|
OK |
200 |
Empty CSV file |
Ensure that both from and to dates have the format yyyy-mm-dd. |
Bad request |
400 |
Raw Reports historical lookback is limited to 90 days. |
Use |
Bad request |
400 |
Your API calls limit has been reached for report type |
- |
Bad request | 400 |
Invalid limit type |
report_rows can have the value 200000 or 1000000. |
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 |
|
The token doesn't match the app. Ask an admin to give you the current token. |