Pull API raw data

Premium

For:

Marketers

Last update: March 26, 2023 09:39

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

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
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:

Get the API token. An admin needs to retrieve the token.
Give your developer the API token to be used in the authentication header.
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.
Tell your developer to follow their Pull API raw data instructions in the developer hub.

Parameters

Parameter	Description
from	The date range consists of `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`
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 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_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=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`

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

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