Pull API raw data

Premium
For:
Marketers
Last update:

At a glance: Use this API to get raw data reports in CSV files.

PullAPIRaw_us-en.png

Pull API raw data

  • Pull API lets you get raw data reports for in CSV files. Learn more about raw data reports
  • Filter by options available: Media source, date range, in-app event name, and geo. 
  • Additional capabilities in Pull API are:
    • Select currency
    • Select timezone

Raw data reports available via Pull API

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
Retargeting
Conversions Record of a user opening the app after engaging with a retargeting campaign. Real-time
In-app events In-app events performed by the user during the re-engagement window. Real-time
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

Using Pull API raw data

To use Pull API raw data:

  1. AppsFlyerAdmin_us-en.pngGet the API token. An admin needs to retrieve the token.
  2. Give your developer the API token to be used in the authentication header.
  3. Give your developers the parameters to input when they make the API call, as described in the sections that follow. The parameters determine what the report focuses on, how it's organized, and provide a reporting timeframe.
  4. Tell your developer to follow their Pull API raw data instructions in the developer hub.

Parameters

Parameter Description
from
  • The date range consists of fromand 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

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 Meta ads, set category and media source to facebook
  • For X Ads, 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_download_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=preferredthe app-specific currency is used. Meaning the currency set in the app settings.

Example: If the app-specific currency is EUR, by sending currency=preferredthe 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 usetimezone=+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
from_install time
  • The date range consists of fromand to parameters. The dates relate to the activity date.
  • Format: yyyy-mm-dd
  • Example: 2010-01-01 
to_install_time

End date. As for from_install time
agency

To limit (filter) the call to a specific agency.

Protect360 fields

See the Protect360 raw data guide

Time frame fields

If the API 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

Additional report fields are not added to the default list of fields so that new fields don't impact your existing 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.
  • Example: additional_fields=device_download_time,deeplink_url

Default fields

Default Pull API fields
Attributed Touch Type
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

Additional information

Traits and limitations

Trait Comments 
API token type required AppsFlyerAdmin_us-en.pngV2.0 token
Ad network access No
Agency access Yes
Agency transparency Yes. However, note that if you use both the agency filter and media source filters, the media source filters don't apply for non-transparent agencies. This means that for non-transparent agencies, all data is included; not just data from the filtered media sources. 
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.
Install_date from and install_date_to Install date range must be earlier than the activity date range. 

Troubleshooting

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 timezoneparameter. If you don't, data is sent using UTC and not your app time zone. 

See also