TUNE Aggregate Exports & API

Overview

📘

For ex-TUNE Clients Only

This feature is currently only available for ex-TUNE clients and replicates the TUNE endpoints available via https://api.mobileapptracking.com/v2/advertiser/stats/actuals/export.

The Branch Aggregate Exports find and queue aggregate data that match your search criteria for export. Unlike the Custom Exports which contains individual logs for each attribution related to your mobile app, the Aggregate Exports include customizable visualizations of your data of interest.

🚧

Data Changes Post iOS 14.5

Apple requires users to opt into sharing their device data through Apple's AppTrackingTransparency framework. When an install is attributed to paid ads, a 2nd install event will fire post user opt-in

Opt-ins will affect your final install count. Our recommendation is to delay pulling aggregate data for as long as you are allowing opt-ins.

For additional information on changes post iOS 14.5, visit our FAQ Pages

Authentication

Calls to the Aggregate Export API require an api_key query string parameter to be passed with each request. API Keys are generated on a per-user basis and are permanent.

Learn how to retrieve your API key (a.k.a. Access Token)

🚧

Organization Level Access Required

In order to retrieve or reset your API Key/Access Token, you must have access to the Organization level of the account. This functionality is not present at the app level.

Rate & Data Limits

Rate Limits

Rate limits depend on the endpoint you are making a request to.

For creating and checking the status of exports, the rate limit is:

  • 2 requests per second
  • 10 requests per minute
  • 1000 per hour

Data Limits

  • Limited to a maximum of 5k rows on the synchronous endpoint
  • Limited to a maximum of 10k rows on the asynchronous endpoint
  • Can query up to 180 days prior to the date of export.
    • If more records are required, please make multiple requests with smaller time intervals to pull the necessary data in "batches".
  • Can only retrieve up to 40,000 unique values for a single dimension (e.g. campaigns, ad names, etc.)

Date range limits

  • For data older than 7 days, all data is rolled up by day, according to your app's timezone. For the most recent 7 days, it is possible to query intra-day data.

Export Access

In order to access Aggregate Exports, a user will need to have both Aggregate Data andExport access.

1248

For more details on how to give a user the required access, please read Default Access Levels, Users Roles & Permissions.

Third Party Access

Any user with access to an account’s API keys will be able to access Branch’s Custom Export API (and thus unfiltered, log-level data). As a result, we would recommend against providing third parties with the permissions required to view API keys during the invitation process.

Providing Agencies/Partners API Access

If you work with an agency that runs your advertising campaigns and want to give them access to export the subsequent data, you can provide them with access to the Custom Export API.

To provide an agency team member with access to the Custom Export API:

  1. In the left-hand navigation, under Setup & Testing, click on Account Settings.
  2. On the Account Settings page, click on the Agencies tab.
  3. Expand the agency in question, find the agency team member you want to give access to, hover on the button in the Actions column and click Edit.
  4. In the Edit Agency Team Member modal:
    1. Under Access Level, check the Export box.
    2. Under Permissions, check the Aggregate Data box.
  5. Optional: add data filters
    1. Under Data Filters, toggle any necessary data filters on/blue. Exported data will be filtered accordingly.
  6. Click Save.
1242

🚧

Agency-Tagged Data

If you do not enable the Only Show Agency-Tagged Data data filter, the Agency Team Member will be able to export aggregate data associated with all of your campaigns, regardless if they are associated with them or not.

Available Topics to Export

The following log topics are available via the Aggregate Export API:

  • Clicks
  • Events
  • Impressions
  • Installs
  • Opens
  • Revenue USD

📘

Info

Branch does not support exports of the infrequently-used update and postbacks TUNE topics.

🚧

IP Discrepancies

Geographic data, such as country and city, may not be available for a very small percentage of events where the IP cannot be resolved to a location.

Available Fields

Tune Field

TUNE Human Readable

ad_network_id

Ad Network ID

ad_network.name

Ad Network Name

advertiser_id

Advertiser ID

advertiser.name

Advertiser Name

advertiser_sub_ad.name

My Ad Name

advertiser_sub_ad.ref

My Ad Ref

advertiser_sub_adgroup.name

My AdGroup Name

advertiser_sub_adgroup.ref

My AdGroup Ref

advertiser_sub_campaign.name

My Campaign Name

advertiser_sub_campaign.ref

My Campaign Ref

advertiser_sub_keyword.name

My Keyword Name

advertiser_sub_keyword.ref

My Keyword Ref

advertiser_sub_placement.name

My Placement Name

advertiser_sub_placement.ref

My Placement Ref

advertiser_sub_publisher.name

My Publisher Name

advertiser_sub_publisher.ref

My Publisher Ref

advertiser_sub_site.name

My Site Name

advertiser_sub_site.ref

My Site Ref

country.code

Country Code

device_type

Device Type

publisher_sub_ad.name

Publisher Sub Ad Name

publisher_sub_ad.ref

Publisher Sub Ad Ref

publisher_sub_adgroup.name`

Publisher Sub AdGroup Name

publisher_sub_adgroup.ref

Publisher Sub AdGroup Ref

publisher_sub_campaign.name`

Publisher Sub Campaign Name

publisher_sub_campaign.ref

Publisher Sub Campaign Ref

publisher_sub_keyword.name

Publisher Sub Keyword Name

publisher_sub_placement.name

Publisher Sub Placement Name

publisher_sub_publisher.name

Publisher Sub Publisher Name

publisher_sub_site.name

Publisher Sub Site Name

site_id

Site ID

timestamp

Timestamp

wurfl_device_os

Device OS

wurfl_model_name

Model Name

attributed

Attributed

🚧

Discontinued Fields

Some fields have very limited value to our customers and as such have been discontinued. Discontinued fields will not be available via the Custom Export API. Please work with your CSM or our Support team if you have questions or concerns.

Including Fields from Related Data Objects

Related objects no longer use periods ( . ) to access the properties on the object. Rather, field names use underscores ( _ ) only.

For example, site_event.id will now be exported as site_event_id.

Building the Export Request

Find and queue all records that match search criteria for export; returns a “handle” to be used in the download export request.

Building the Export Request

Type

Required

Description

api_key

String

Y

Your API Key

start_date

Date

Y

The beginning datetime for the requested results, provided in ISO-8601 format.

Dates without offsets (i.e. a timezone) default to the value provided for the timezone parameter. If the timezone parameter is not specified, the dates timezone defaults to UTC. Date must be within the last 120 days. Example: 2016-01-01T00:00:00Z

end_date

Date

Y

The end datetime for the requested results, provided in ISO-8601 format.

Dates without offsets (i.e. a timezone) default to the value provided for the timezone parameter. If the timezone parameter is not specified, the dates timezone defaults to UTC. Example: 2016-01-01T23:59:59Z

filter

Filter

N

Filter by fields and boolean operators against fields of the Actuals endpoint. Example: &filter=(mat_id="3bc15517-92d5-4b7f-9837-e9a30d6fb9b8")+AND+("site_event_id"=1844998705)

fields

Comma Separated List

Y

List of comma-separated fields from the LogInstalls model desired in results. Defaults to display all fields

limit | Integer

Y

Limit the number of items returned per request. Maximum allowed value is 2 million. If more than 2 million records are required, please make multiple requests with smaller time intervals to pull the data needed in “batches”;

sort

Sort

N

Fields followed by the direction (asc or desc). Results can be sorted with multiple fields and directions.

Optional parameter

group

Array

N

Group items returned by the field selected.

timestamp

String

N

Set to breakdown stats by timestamp. Choices include: hour, datehour, date, week, month.

Optional parameter.

format

Nullable String

N

Format of the response; can be either JSON or CSV. If not selected, defaults to CSV.

response_timezone

Timezone

N

Timezone in which result dates are conveyed; defaults to the timezone set in your account.

Sample Export Request

https://api.mobileapptracking.com/v2/advertiser/stats/actuals/export.json?api_key=4c5b6461026cb0caff3c66bef881b4af&start_date=2018-08-01+00%3A00%3A00&end_date=2018-08-18+00%3A00%3A00&fields[]=opens&fields[]=installs&fields[]=events&fields[]=publisher_sub_adgroup_id&fields[]=publisher_sub_campaign_id&timestamp=date&format=json

Sample Export Response

{
  "status_code": 200,
  "response_size": "334",
  "throttle": {
    "decision": "Permit",
    "decision_authority": "Endpoint",
    "decision_state": "Always Permit",
    "object_key": "/advertiser/stats/actuals/export",
    "virtual_record": false,
    "next_reset": "N/A",
    "count_remaining": 0,
    "limit": 0,
    "interval": 0
  },
  "data": {
    "job_id": "5a494d8b-e5f9-4561-b71d-5c5ee4ed087d"
  }
}

Building the Download Export Request

Finds and exports requested queue (by handle) and provides URL location for download.

Parameter

Type

Required

Description

advertiser_id

String

Y

Your TUNE Advertiser ID

api_key

String

Y

Your API Key

handle

String

Y

The ID returned by the log export queue.

Sample Report Status Request

https://api.mobileapptracking.com/v2/export/download.json?api_key=REMOVED&job_id=5a494d8b-e5f9-4561-b71d-5c5ee4ed087d

Sample Report Status Response

{"status_code":200,"response_size":"437","data":{"status":"complete","percent_complete":100,"data":{"format":"json","url":"https:\/\/s3.amazonaws.com\/hasdevfiles\/9da89700-ee8e-42f1-932f-7b9459a614dd.json?response-content-disposition=attachment%3B%20filename%3D%229da89700-ee8e-42f1-932f-7b9459a614dd.json%22&AWSAccessKeyId=AKIAIHT2RGXNQAIUT7ZA&Expires=1547654522&Signature=mfXJ7fGZeZZ%2FYPnEHssGopvdpxk%3D"},"report_schedule_id":null}}

Sample Download Report

curl 'https://s3.amazonaws.com/hasdevfiles/3bce2890-97c8-44e0-985b-9c5505b7ec4a.json?response-content-disposition=attachment%3B%20filename%3D%223bce2890-97c8-44e0-985b-9c5505b7ec4a.json%22&AWSAccessKeyId=AKIAIHT2RGXNQAIUT7ZA&Expires=1535997897&Signature=v9WhAulFDVmfaR%2FzAg3uvh8DVAc%3D'

Sample Report

[
  {
    "publisher_sub_campaign_id": "975222707",
    "publisher_sub_adgroup_id": "666119300",
    "installs": 0,
    "opens": 0,
    "events": 0
  },
  ...
  {
    "publisher_sub_campaign_id": "0",
    "publisher_sub_adgroup_id": "0",
    "installs": 12,
    "opens": 13,
    "events": 31
  }
]