Introduction
AppsFlyer's CSV data reports are available for manual download through the Export Data page, and also via the Pull API.
Pull API enables app owners to receive CSV files of data about their apps by using specific URLs containing query parameters. Pulled reports can either be in aggregated or raw data forms.
The Pull API links are all available in the API Access Page in each app's dashboard.
Important!
The next sections discuss manual creation of Pull API links. When manually creating Pull API links, make sure that parameters are in lowercase as they are case-sensitive.
Raw Data reports provide all data for installs and in-app events.
API Parameters - Required
- api_token
- Is the user's external API Authorization Key: "{Account owner API Key should be used}"
- from
- Report start date in the format of "yyyy-mm-dd" or "yyyy-mm-dd hh:mm". For example: 2010-01-01 or 2010-01-01%2000%3A15 - (The hours parameter is for raw reports only).
- to
- Report end date. Same format as from
API Filtering Parameters - Optional
Filter by Media Source
Filtering the reports to list only a specific media source is available by adding both the category and media source parameters to the request URL:
- category
- To get Facebook data set
category=facebookon the URL. For any other specific media source setcategory=standard - media_source
- Supply the name of a single media source (
media_source=[SOURCE_NAME]) as it appears on AppsFlyer's dashboard.
Examples
1: Google Adwords Filtered Report
https://hq.appsflyer.com/export/com.greatapp/installs_report/v5?api_token=xxxx
&from=2018-04-09&to=2018-05-09&category=standard&media_source=googleadwords_int
2: Facebook Filtered Report
https://hq.appsflyer.com/export/com.greatapp/installs_report/v5?api_token=xxxx
&from=2018-04-09&to=2018-05-09&category=facebook&media_source=facebookFilter by Event name
Filter the raw in-app events report data to include only a specific event, by using the event_name parameter. To filter multiple events use a comma separated list of events.
For example: event_name=af_purchase,ftd
For Retargeting Exports
Use reattr=true to get results attributed to retargeting campaigns.
Custom Reports with Pull API
- fields
Pull API supports customizing raw data reports with selectable fields (v5 and up). This enables marketers to download only relevant information to suit their requirements.
To specify the requested fields, append the following fields parameter to the API call.
Each column you request should be added to the fields parameter by specifying the API Column Name as it appears here. Example: fields=country_code,city
&fields=API_Name_A,API_Name_BExample
Pull the list of all cities and their respective country codes that brought installs -https://hq.appsflyer.com/export/id341333333/installs_report/v5?api_token=24b7b9fe-6ddd-4ddd-94c8-xxxxxxxxxxx&from=2017-03-09&to=2017-03-10&fields=country_code,city
The full list of fields and their API names can be found here.
Notes
- Currently Filtering is not supported when customizing the report with the Fields option. To perform both build the URL with field customization and then filter the results manually on your spreadsheet.
- The Fields option does not support the additional_fields (explained below).
Additional Fields
Through Pull API you can add some fields, that complete the picture for raw data installs and in-app events in some cases.
To add new fields add "&additional_fields=" to the tracking link, followed by the comma-separated list of additional fields. See the Pull API examples below.
The result is a CSV report with added columns, that contain information when relevant.
| Field name | Relevant for |
|---|---|
| rejected_reason rejected_reason_value |
Validation Rules |
|
blocked_reason |
Protect360 (Anti-Fraud solution) |
| install_app_store | Out-of-store Android markets |
| custom_data | Retrieving custom data |
| gp_referrer | Google Play field - click here for more info. |
| gp_click_time | Google Play field - click here for more info. |
| gp_install_begin | Google Play field - click here for more info. |
Time Zone and Currency
timezone (optional)
You can get the Pull API raw data in ANY valid time zone:
1. Add &timezone=[Joda-Time] in the Pull API link to receive the report in the preferred timezone (see note below)
2. Add &timezone=[Numerical value] in the Pull API link to receive the report in the specified numerical timezone. For example: for time zone UTC+10:00 add on the link &timezone=%2B10:00
3. Otherwise the data is received in the default UTC time zone.
Notes
1. Joda-Time time zone format takes into account daylight saving time.
2. The Joda-Time value MUST be identical to the possible values in the app settings page. For example, if you wish to get data in France's time zone, check the time zone list in the app settings page, which is "France - Paris" for France. The timezone value in the Pull API URL should be &timezone=France/Paris. Pulling data in the selected time zone is only available from the date when the time zone setting was made. Any data prior to the date of the change, is shown as default GMT.
currency (optional)
- Is used to receive the Revenue and Cost data in your selected currency, rather than in USD, which is the default option. This is set by the account admin.
To receive the data in your preferred currency, please add the following to your request link: ¤cy=preferred
- is used to receive Revenue and Cost data in your selected currency.
Note
Generally, the Pull API URLs do not need to be encoded. However, if using parameters that have non-URL compatible values, you will need to URL encode them. For example, using hours and time zone parameters.
API Policy and Usage Limitations
AppsFlyer's API Policy ensures high quality of service to the users of pull API by limiting the total number of daily requests and preventing abuse of the service.
See details about the API policy for aggregated data via Pull API and for raw data via Pull API.
The maximum number of records per report is 200K. If you get a report that has 200K rows then you have some results that were left out.
Tip
If your daily results exceed 200K rows you can split your files according to the date AND the time of day, using the "yyyy-mm-dd hh:mm" date/time format in the from and to parameters on the Pull API URL.
For example - an app owner has up to 300K new daily installs from all sources. The app owner decides to split the daily Pull API calls to 2 calls every 12 hours. The first URL call includes from=yyyy-mm-dd 00:00&to=yyyy-mm-dd 11:59 and the second from=yyyy-mm-dd 12:00&to=yyyy-mm-dd 23:59 (before encoding)
Note
By default, the Pull API Performance Report shows Facebook data at campaign level only. Add "&category=facebook" to enable the report to present Facebook information at both the Ad Set and Ad level. This is relevant for Facebook only.
API Security
All Pull API links use secure crypted https connections.
For more details go here.
Pull API Link Examples
| Report Category | Report Type | Link Example |
|---|---|---|
| Raw Data Reports | Installs Report | https://hq.appsflyer.com/export/id123456789/installs_report/v5?api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd |
| In-App Events Report | https://hq.appsflyer.com/export/id123456789/in_app_events_report/v5?api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd | |
| Uninstalls Report |
|
|
| Organic Installations Report | https://hq.appsflyer.com/export/id123456789/organic_installs_report/v5?api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd | |
| Organic In-App Events Report | https://hq.appsflyer.com/export/id123456789/organic_in_app_events_report/v5?api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd | |
| Validation Rules Reports | Invalid Installs Report | https://hq.appsflyer.com/export/id123456789/invalid_installs_report/v5?api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd&additional_fields=rejected_reason,rejected_reason_value |
| Invalid In-App Events Report | https://hq.appsflyer.com/export/id123456789/invalid_in_app_events_report/v5?api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd&additional_fields=rejected_reason,rejected_reason_value |
API Version (V5)
- Unchanged:
-
The existing API (v4) is still available for use
-
The version does not apply any change to the file format or headers
-
Performance Reports provide details of the effectiveness of advertising campaigns.
API Parameters - Required
- api_token
- Is the user's external API Authorization Key: "{Account owner API Key should be used}". The API token is displayed ONLY to the account owner
- from
- Report start date in the format of "yyyy-mm-dd" or "yyyy-mm-dd hh:mm". For example: 2010-01-01 or 2010-01-01%2000%3A15 - (The hours parameter is for raw reports only)
- to
- Report end date. Same format as from
API Filtering Parameters - Optional
Filter by media source
Filtering the reports to list only a specific media source is available by adding both the category and media source parameters to the request URL:
- category
- To get Facebook data set
category=facebookon the URL. For any other specific media source setcategory=standard - media_source
- Supply the name of a single media source (
media_source=[SOURCE_NAME]) as it appears on AppsFlyer's dashboard.
Examples
1: Google Adwords Filtered Report
https://hq.appsflyer.com/export/com.greatapp/partners_report/v5?api_token=xxxx
&from=2018-04-09&to=2018-05-09&category=standard&media_source=googleadwords_int2: Facebook Filtered Report
https://hq.appsflyer.com/export/com.greatapp/partners_report/v5?api_token=xxxx
&from=2018-04-09&to=2018-05-09&category=facebook&media_source=facebookFor Retargeting Exports
Use reattr=true to get results attributed to retargeting campaigns.
Time Zone and Currency
timezone (optional)
You can get the aggregated data via Pull API in either UTC or the app's preferred time zone, which is set in the App Settings page:
1. Add &timezone=[selected Joda-Time] in the Pull API link to receive the report in the app's preferred timezone (see note below)
2. Otherwise the data is received in the default UTC time zone.
Notes
1. Joda-Time time zone format takes into account daylight saving time.
2. The Joda-Time value MUST be identical to the value set in the app settings page. For example, if the selected time zone in the app settings is "France - Paris", the timezone value in the Pull API URL should be &timezone=France/Paris
currency (optional)
- Is used to receive the Revenue and Cost data in your selected currency, rather than in USD, which is the default option. This is set by the account admin.
currency=preferred
- is used to receive Revenue and Cost data in your selected currency.
Note
Generally, the Pull API URLs do not need to be encoded. However, if using parameters that have non-URL compatible values, you will need to URL encode them. For example, using hours and time zone parameters.
API Policy
AppsFlyer's API Policy ensures high quality of service to the users of pull API by limiting the total number of daily requests and preventing abuse of the service.
The maximum number of records per report is 200K. If you get a report that has 200K rows then you have some results that were left out.
Tip
If your daily results exceed 200K rows you can split your files according to the date AND the time of day, using the "yyyy-mm-dd hh:mm" date/time format in the from and to parameters on the Pull API URL.
For example - an app owner has up to 300K new daily installs from all sources. The app owner decides to split the daily Pull API calls to 2 calls every 12 hours. The first URL call includes from=yyyy-mm-dd 00:00&to=yyyy-mm-dd 11:59 and the second from=yyyy-mm-dd 12:00&to=yyyy-mm-dd 23:59 (before encoding)
Note
By default, the Pull API Performance Report shows Facebook data at campaign level only. Add "&category=facebook" to enable the report to present Facebook information at both the Ad Set and Ad level. This is relevant for Facebook only.
API Security
All Pull API links use secure crypted https connections.
For more details go here.
Pull API Link Examples
| Report Category | Report Type | Link Example |
|---|---|---|
| Performance Reports | Partners Report | https://hq.appsflyer.com/export/id123456789/partners_report/v5?api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd |
| Partners Daily Report | https://hq.appsflyer.com/export/id123456789/partners_by_date_report/v5?api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd | |
| Daily Report | https://hq.appsflyer.com/export/id123456789/daily_report/v5?api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd | |
| Geo Report | https://hq.appsflyer.com/export/id123456789/geo_report/v5?api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd | |
| Geo Daily Report | https://hq.appsflyer.com/export/id123456789/geo_by_date_report/v5?api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd |
API Version (V5)
- Changes:
-
In Version (v5) performance reports that contain multiple partners, group Facebook data by campaign only. Performance reports that contain Facebook data only (by specifying &category=facebook) group data by campaign and ad group.
-
Export data page for aggregated reports uses the API version (v5)
-
- Unchanged:
-
The existing API (v4) is still available for use
-
The version does not apply any change to the file format or headers
-
Note
To use V4 Performance Reports, change v5 to v4.
For example, the v5 (in red) should be changed to v4.
https://hq.appsflyer.com/export/i{app_
P360 aggregated data as appears in the advanced detection table in the dashboard.
API Parameters - Required
- api_token
- Is the user's external API Authorization Key: "{Account owner API Key should be used}"
- from
- Report start date in the format of "yyyy-mm-dd" or "yyyy-mm-dd hh:mm". For example: 2010-01-01 or 2010-01-01%2000%3A15 - (The hours parameter is for raw reports only).
- to
- Report end date. Same format as from
API Filtering Parameters - Optional
Filter by media source
Filtering the reports to list only a specific media source is available by adding:pid=media source name.
Time Zone and Currency
timezone (optional)
You can get the P360 aggregated data via Pull API in either UTC or the app's preferred time zone, which is set in the App Settings page:
1. Add &timezone=preferred in the Pull API link to receive the report in the app's preferred timezone
2. Otherwise the data is received in the default UTC time zone.
currency (optional)
- Is used to receive the Revenue and Cost data in your selected currency, rather than in USD, which is the default option. This is set by the account admin.
currency=preferred
- is used to receive Revenue and Cost data in your selected currency.
Note
Generally, the Pull API URLs do not need to be encoded. However, if using parameters that have non-URL compatible values, you will need to URL encode them. For example, using hours and time zone parameters.
API Security
All Pull API links use secure crypted https connections.
For more details go here.
Pull API Link Examples
| Report Category | Report Type | Link |
|---|---|---|
|
P360 - Aggregated Advanced Detection Reports |
Partners Report | https://hq1.appsflyer.com/master/p360/reports/v4?api_token=<API Token>&app_id=<APP_ID>&from=yyyy-mm-dd&to=yyyy-mm-dd&groupings=pid,af_siteid&kpis=protect360_total_installs,install_fraud_new_devices_installs,install_fraud_new_devices_installs_rate,install_fraud_new_devices_loyal_user_rate,install_fraud_lat_devices_installs,install_fraud_lat_devices_install_rate,install_fraud_lat_devices_loyal_user_rate,install_fraud_suspicious_devices_installs,install_fraud_suspicious_devices_install_rate,install_fraud_suspicious_devices_loyal_user_rate,install_fraud_clean_device_installs,install_fraud_clean_device_install_rate,install_fraud_clean_device_loyal_user_rate,clicks,cr,click_flood_under_5_min_rate,click_flood_from_5_to_60_min_rate,click_flood_over_60_min_rate,contribution_rate,install_hijacking_up_to_10_sec_rate,install_hijacking_10_to_30_sec_rate,install_hijacking_over_30_sec_rate |
| Partners Daily Reports | https://hq1.appsflyer.com/master/p360/reports/v4?api_token=<API-TOKEN>&app_id=<APP_ID>&from=yyyy-mm-dd&to=yyyy-mm-dd&groupings=pid,af_siteid,install_time&kpis=protect360_total_installs,install_fraud_new_devices_installs,install_fraud_new_devices_installs_rate,install_fraud_new_devices_loyal_user_rate,install_fraud_lat_devices_installs,install_fraud_lat_devices_install_rate,install_fraud_lat_devices_loyal_user_rate,install_fraud_suspicious_devices_installs,install_fraud_suspicious_devices_install_rate,install_fraud_suspicious_devices_loyal_user_rate,install_fraud_clean_device_installs,install_fraud_clean_device_install_rate,install_fraud_clean_device_loyal_user_rate,clicks,cr,click_flood_under_5_min_rate,click_flood_from_5_to_60_min_rate,click_flood_over_60_min_rate,contribution_rate,install_hijacking_up_to_10_sec_rate,install_hijacking_10_to_30_sec_rate,install_hijacking_over_30_sec_rate | |
| Geo Report | https://hq1.appsflyer.com/master/p360/reports/v4?api_token=<API-Token>&app_id=<APP_ID>&from=yyyy-mm-dd&to=yyyy-mm-dd&groupings=geo&kpis=protect360_total_installs,install_fraud_new_devices_installs,install_fraud_new_devices_installs_rate,install_fraud_new_devices_loyal_user_rate,install_fraud_lat_devices_installs,install_fraud_lat_devices_install_rate,install_fraud_lat_devices_loyal_user_rate,install_fraud_suspicious_devices_installs,install_fraud_suspicious_devices_install_rate,install_fraud_suspicious_devices_loyal_user_rate,install_fraud_clean_device_installs,install_fraud_clean_device_install_rate,install_fraud_clean_device_loyal_user_rate,clicks,cr,click_flood_under_5_min_rate,click_flood_from_5_to_60_min_rate,click_flood_over_60_min_rate,contribution_rate,install_hijacking_up_to_10_sec_rate,install_hijacking_10_to_30_sec_rate,install_hijacking_over_30_sec_rate | |
| Geo Daily Report | https://hq1.appsflyer.com/master/p360/reports/v4?api_token=<API-TOKEN>&app_id=<APP_ID>&from=yyyy-mm-dd&to=yyyy-mm-dd&groupings=geo,install_time&kpis=protect360_total_installs,install_fraud_new_devices_installs,install_fraud_new_devices_installs_rate,install_fraud_new_devices_loyal_user_rate,install_fraud_lat_devices_installs,install_fraud_lat_devices_install_rate,install_fraud_lat_devices_loyal_user_rate,install_fraud_suspicious_devices_installs,install_fraud_suspicious_devices_install_rate,install_fraud_suspicious_devices_loyal_user_rate,install_fraud_clean_device_installs,install_fraud_clean_device_install_rate,install_fraud_clean_device_loyal_user_rate,clicks,cr,click_flood_under_5_min_rate,click_flood_from_5_to_60_min_rate,click_flood_over_60_min_rate,contribution_rate,install_hijacking_up_to_10_sec_rate,install_hijacking_10_to_30_sec_rate,install_hijacking_over_30_sec_rate | |
| Partners Campaign Report | https://hq1.appsflyer.com/master/p360/reports/v4?api_token=<API_TOKEN>&app_id=<APP_ID>&from=yyyy-mm-dd&to=yyyy-mm-dd&groupings=pid,af_siteid,c&kpis=protect360_total_installs,install_fraud_new_devices_installs,install_fraud_new_devices_installs_rate,install_fraud_new_devices_loyal_user_rate,install_fraud_lat_devices_installs,install_fraud_lat_devices_install_rate,install_fraud_lat_devices_loyal_user_rate,install_fraud_suspicious_devices_installs,install_fraud_suspicious_devices_install_rate,install_fraud_suspicious_devices_loyal_user_rate,install_fraud_clean_device_installs,install_fraud_clean_device_install_rate,install_fraud_clean_device_loyal_user_rate,clicks,cr,click_flood_under_5_min_rate,click_flood_from_5_to_60_min_rate,click_flood_over_60_min_rate,contribution_rate,install_hijacking_up_to_10_sec_rate,install_hijacking_10_to_30_sec_rate,install_hijacking_over_30_sec_rate |
API Version (V5)
- Changes:
-
In Version (v5) performance reports that contain multiple partners, group Facebook data by campaign only. Performance reports that contain Facebook data only (by specifying &category=facebook) group data by campaign and ad group.
-
Export data page for aggregated reports uses the API version (v5)
-
- Unchanged:
-
The existing API (v4) is still available for use
-
The version does not apply any change to the file format or headers
-
Note
To use V4 Performance Reports, change v5 to v4.
For example, the v5 (in red) should be changed to v4.
https://hq.appsflyer.com/export/i{app_
API Errors and Troubleshooting
This section discusses common API erros and how to handle them.
The Supplied API Token is Invalid
Error Message
The supplied API token is invalid
Error Code
401
Description
The server could not authenticate the request. The API token is either missing or invalid.
How to Solve
Make sure that the URL contains the correct API token. The API token is passed in the api_token parameter.
API Querying Date Range is Limited to Past 3 Months
Error Message
The server could not comply with the request since it is either malformed or otherwise incorrect.
API querying date range is limited to past 3 months
Error Code
400
Description
This error messages is returned when you try to query data that spans over a 3-month range.
How to Solve
Make sure to limit the date range to 3 months or less using the to and from parameters.