Using Pull API raw-data

At a glance: Use URIs to get your AppsFlyer 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.
The filter by options are: Media source, date range, in-app event name, and geo.
Selectable timezone and currency
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

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	Uniform resource identifier sometimes similar to a web address (URL) containing the report specification. Template URIs are available on the API page in the Dashboard.

Guide for team members

About URI templates

URI templates available in the dashboard are populated with the app ID and report type.
They have placeholders 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.
Postback URIs aren't available via the dashboard. Postback URIs in a spreadsheet.

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:
1. 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.
2. 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 &.
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	The date range consists of a `from`and `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 space needs to be encoded as shown here `from=2020-04-01%2001:00:00` - In general, browsers will encode the space. Example: 2010-01-01 or 2010-01-01 20:15 (Hours and minutes parameters available for raw data reports).
to	End date. As for `from`

Raw data optional parameters
Parameter	Description
media_source	`media_source`: To limit (filter) the call to a specific media source. Set both the `media_source` and `category` parameters as follows: For Facebook set category and media source to facebook For Twitter set category and media source to twitter For all other media sources set category to standard and media source to the name of the media source. Examples `media_source=facebook&category=facebook` `media_source=abc_example&category=standard`
maximum_rows	Maximum number of rows returned by a single API call. [Default] if no value is sent, up to 200K rows 200000: Up to 200K rows return 1000000: Up to 1M rows return Example: `maximum_rows=1000000` enables up to 1M rows.
event_name	Filter in-app events by specified events. Select multiple events by using a comma-separated list. Example: `event_name=af_purchase,ftd`
reattr	Set retargeting attribution data. [Default] If false, user acquisition data (UA) campaigns returns. If true, retargeting attribution data returns. Example:`reattr=true`
additional_fields	To get additional fields in addition to the default fields. Example: `additional_fields=device_donwload_time,deeplink_url`
currency	Currency of the revenue and cost [Default] If the parameter is not sent, data returns as USD. Meaning, do nothing and results return in USD. If you send, `currency=preferred`the app-specific currency is used. Meaning the currency set in the app settings. Example: If the app-specific currency is EUR, by sending `currency=preferred`the values return in EUR.
timezone	[Default] Data returns using UTC. To get data in the app-specific timezone, add `timezone` as shown in this section to the call: `timezone=[Numerical value]` Example: For time zone UTC+10:00 use`timezone=+10:00` Note!: The `+`,`-`, and `:` need to be encoded. Example: +10:00 encodes to `%2B10%3A00`
geo	Filter the data by country code. Limitation: You can set only one country code filter per API call. Example: `geo=ZA`

Protect 360

See the Protect360 raw-data guide

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:

from=2019-12-29
Begins on this date at the beginning of the day at 00:00

to=yyyy-mm-dd 12:00

Example:

to=2019-12-29 12:00
Continues up to 11:59:59, not 12:00

Option A: Second API call

Example:

&from=2019-12-29 12:00&to=2019-12-29

Starts noon 29 Dec 2019
Ends midnight 29 Dec 2019

from=yyyy-mm-dd 12:00

Example:

from=2019-12-29 12:00
Starts from and includes 12:00

to=yyyy-mm-dd

Example:

to=2019-12-29
Ends at midnight

Option B: Second API call

from=yyyy-mm-dd 12:00

Example:

from=2019-12-29 12:00
Starts from and includes 12:00

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

+1 = next day at 00:00

Example:

to=2019-12-30 00:00
Meaning before any time has elapsed on 30 Dec.

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
Trait	Comments
API token type required	V1.0 token
Ad network access	No
Agency access	Yes
Agency transparency	Yes
App-specific currency	Yes
App-specific timezone	Yes
Data freshness	Equivalent to the availability of the data in the overview dashboard. Reports updated with a lag of a few hours: Organic in-app events Reports updated Daily: Uninstalls Post-attribution in-app events Ad revenue
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 calls return a max. of 200K/1M rows. If a report has exactly 200K/1M rows, then assume rows are missing. Use the maximum_rows parameter to select the maximum number of rows. Make multiple API calls, using from/to parameters that include the time of day.

API error codes and troubleshooting

Error codes, symptoms, and solutions
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 `timezone`parameter. If you don't, data is sent using UTC and not your app time zone.
OK	200	Empty CSV file	`addtional_fields`appears more than once in the URI.
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 `to` and `from` to limit the date range to 3 months or less.
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.

Are you looking for Pull API aggregate data?

Pull API raw–data characteristics

Terminology

Guide for team members

About URI templates

Getting your first Pull API report tutorial

Raw data Pull API parameters

URI parameters raw data

Protect 360

Time range by date and time

Additional fields

Example

Pull API for developers

Additional information

Differences between Pull API V4 and V5.

Traits and limitations

API error codes and troubleshooting

Articles in this section

Page contents:

Using Pull API raw-data

Are you looking for Pull API aggregate data?

Pull API raw–data characteristics

Terminology

Guide for team members

About URI templates

Getting your first Pull API report tutorial

Raw data Pull API parameters

URI parameters raw data

Protect 360

Time range by date and time

Additional fields

Example

Pull API for developers

Additional information

Differences between Pull API V4 and V5.

Traits and limitations

API error codes and troubleshooting

Articles in this section

Related articles

Page contents: