Pull API raw data


At a glance: Use URIs to get your raw data reports in CSV files.


Pull API raw data characteristics

 Related reading: Selecting the right data delivery tool/reporting API


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.

  • Uniform resource identifier is sometimes similar to a web address (URL) containing the report specification.
  • Template URIs are available on the API page in the Dashboard.

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:

To download a report from dev hub: 

  1. Go to the AppsFlyer dev hub API reference.


  2. 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.

  3. Fill in all the required fields 
  4. The URI template displays on the right. 
  5. Copy the URI by clicking on the copy icon.
  6. Open a new tab in your browser, and paste the URI.
  7. 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.
In-app events Records the events performed by users.
Uninstalls Records when a user uninstalls the app.
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.
Organic in-app events
Records details about events performed by users.
Organic uninstalls
Records users uninstalling the app.
Organic reinstalls
Records ad revenue for users attributed to a retargeting media source during the re-engagement window.
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
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. 
  • The date range consists of fromand to parameters. The dates relate to the activity date.
  • Format: yyyy-mm-ddyyyy-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: 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 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. 

Filter in-app events by specified events. Select multiple events by using a comma-separated list.



Set retargeting attribution data.

  • [Default] If false, user acquisition data (UA) campaigns returns.
  • If true, retargeting attribution data returns.
  • Example:reattr=true

To get additional fields in addition to the default fields. 

Example: additional_fields=device_donwload_time,deeplink_url


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.


[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

Filter the data by country code.

Limitation: You can set only one country code filter per API call. 

Example: geo=ZA

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=2019-12-29
  • Begins on this date at the beginning of the day at 00:00

to=yyyy-mm-dd 12:00


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

Option A: Second API call 



&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


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




  • to=2019-12-29
  • Ends at midnight


Option B: Second API call

from=yyyy-mm-dd 12:00


  • 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


  • 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.


URI call example with additional fields:

https://hq1.appsflyer.com/api/raw-data/export/app/<APP ID HERE>/installs_report/v5?

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
Media Source
Campaign ID
Adset 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
Country Code
Postal Code
AppsFlyer ID
Advertising ID
Android ID
Customer User ID
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 AppsFlyerAdmin_us-en.pngV2.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 timezoneparameter. If you don't, data is sent using UTC and not your app time zone. 

OK 200 Empty CSV file

addtional_fieldsappears more than once in the URI.



Empty CSV file

Ensure that both from and to dates have the format yyyy-mm-dd.

Bad request


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


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.


Supplied API token is invalid 

Ask an admin for the current token.


Account may be suspended.

Log in to the dashboard and check the account status. 

Not found



The token doesn't match the app. Ask an admin to give you the current token.