At a glance: Use URIs to get raw data reports in CSV files.
Are you looking for Pull API aggregate data?
Pull API raw–data characteristics
- Descriptions of raw–data report contents
- Reports return as CSV files.
- Data freshness rates are the same as the equivalent report on the Export Data page.
- The filter by options are the same as in the Export Data page being: Media source, date range, in-app event name.
- Additional capabilities in Pull API are:
- Selectable timezone
- The currency of raw data reports is selectable
- Pull API is suited to use by team members and BI developers;
- Team members get reports by pasting URIs in their browser. The URI templates are available in the Dashboard. In AppsFlyer, go to Integration > API access.
- Pull API for BI developers get reports by embedding URIs in scripts.
Example URI template
Related reading:
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 team members
About URI templates
- URI templates available in the dashboard are populated with the app ID and report type.
- They have place holders for the API token and from/to dates which you need to 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 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.
Getting your first Pull API report tutorial
Before you begin:- Ask the admin to provide you with the Pull API token available in the dashboard.
To download a report from the dashboard:
- Go to Integration > API access.
The API access page opens. - Select a report type. For example, Raw data reports > Retargeting conversions.
The URI template displays. - Copy the URI by clicking on it.
- Open a new tab in your browser, paste the URI.
- Edit the URI:
- Replace the token placeholder with the Pull API token provided by the admin.
Example. Replace the token placeholder so that&api_token=12345678-1234-1234-1234-123456789012
. Note! There are no spaces or other punctuation. - Replace the from/to placeholders with dates.
Example:&from=2020-01-20&to=2020-01-31
Note! There are no spaces. Don't delete the &.
- Replace the token placeholder with the Pull API token provided by the admin.
- Click <Enter> to send the API call.
The report downloads.
Raw data Pull API parameters
URI parameters raw data
Parameter | Description |
---|---|
api_token | API Authorization token. In example calls, this is shown as: <API TOKEN HERE>. |
from |
|
to | End date. As for from |
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.
|
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://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 |
---|
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
Differences between Pull API V4 and V5.
Raw data: API V4 is still available for use. No changes are made to file formats and headers.
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 |
Data freshness |
|
Historical data | Y subject to retention policies |
Non-organic data | Y |
Organic data | Y |
Rate limitation |
API limitations for raw data. |
Size limitations |
|
API error codes and troubleshooting
Status | Code | Symptom/message | Solution |
---|---|---|---|
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 the 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 the admin to give you the current token. |