Aggregate API Overview

Overview

The Branch Aggregate API allows you to programmatically query and export aggregate analytics.

Benefits

With the Aggregate API, you can:

Give access to agencies and ad networks to pull aggregate data themselves. Learn more about user permissions and granting access to filtered data.
Give Facebook Marketing Partners (FMP) some visibility through aggregate data.

Limitations

Limitation	Details
Max Number of Records Returned	50,000 Branch may define dynamic record limits based on `organization_id` or `app_id`.
Export Window	Rolling 2 year window.
Max Number of Dimensions	11 dimensions.
Max Number of Days Queried	7 days.
Rate Limits	2 requests per second. 5 requests per minute. 150 requests per hour.

SAN CCI Data

SANs cost/click/impression (CCI) data is not available via the Aggregate API.

Instead, use the Query API and the xx_impression field for getting aggregated data of impressions for SANs.

Try It!

Try out the Aggregate API in your browser, using your Branch data:

Request Aggregate Export

Export Download Status

Getting Started

Prerequisites

In order to use the Aggregate API, you first need to:

Create a Branch Dashboard.
Enable Universal Ads and start running ad campaigns from your Branch account.
Implement the appropriate Branch SDK into your mobile app (iOS | Android).
Make sure you have the appropriate permissions set on your user account. See the Access section for more.

Access

General Access

To access the Aggregate API, a user must have the Aggregate Data Access Level enabled on their account.

Agency Access

If you work with an agency that runs your advertising campaigns and want to give them access to export Aggregate API data, you can assign their account(s) the Aggregate Data Access Level as well.

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

In the left-hand navigation, under Setup & Testing, click on Account Settings.
On the Account Settings page, click on the Agencies tab.
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.
In the Edit Agency Team Member modal:
1. Under Access Level, check the Export box.
2. Under Permissions, check the Aggregate Data box.
Optional: add data filters
1. Under Data Filters, toggle any necessary data filters on/blue. Exported data will be filtered accordingly.
Click Save.

1246

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.

Authentication

Calls to the Async Aggregate 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 (also known as access_token).

NOTE: In order to retrieve or reset your API key/access token, you must have Organizational Level access to the Branch account. This functionality is not present at the App Level.

Usage

Request Aggregate Export

Request Info

Export Request

POST /v2/analytics
Host: api2.branch.io
Content-Type: application/json

Request Headers

Header	Description	Required
`Access-Token`	Key that encapsulates the user's permission with regards to an organization. Obtained from the Branch Dashboard. Needed for authentication.	Yes
`accept`	application/json	Recommended
`content-type`	application/json	Recommended

Request Query Parameters

Parameter	Description	Required
`organization_id` or `app_id`	Unique identifier for app/organization of requested data.	Yes
`limit`	The maximum number of results to return. Default: 50000 Min: 50000 Max: 50000 (unless a higher limit is specified)	No
`format`	Format of returned data. Defaults to CSV.	No

Request Body Parameters

Parameter	Description	Required
`start_date`	The start of the interval time range represented as an ISO-8601 complete date.	Yes
`end_date`	The end of the interval time range represented as an ISO-8601 complete date.	Yes
`data_source`	A string value representing the data source. See topics section for complete list.	Yes
`dimensions`	An array representing dimension(s) to group by. Limit is 11. See dimensions section for complete list. NOTE: If you are querying `skadnetwork-valid-messages`, be sure to set `aggregation` to `total_count`.	No
`filters`	Keys are same as dimensions. Values are an array of values to match for the dimension. An object defining filters to match or disallow certain values.	No
`granularity`	The time granularity that each band value will represent. Granularity levels: - `day` - `week` - `month`Default: `day`NOTE: Do not add `timestamp` to `dimensions` field when setting `granularity` to `day`. Instead, add `name` to the `dimensions` field.	No
`aggregation`	How to count events towards the final result count. Aggregation options: - `unique_count` - `total_count` - `revenue` - `cost` - `cost-in-local-currency`Default: `total_count`NOTE: When querying with a data source of `eo_commerce_event`, the aggregation may also be specified as `revenue`, in which case the counts returned are the sum of revenue from matching events, and not the number of events themselves.	No
`enable_install_calculation`	If `true`, then Branch will de-dupe unattributed installs caused by duplicate events from non-opt-in users coming from paid ads (result from iOS 14.5 privacy changes). Default: `false`	No

Response Info

Response Body Parameters

Parameter	Description
`code`	The response code. Can be `200`, `400`, or `500`.
`job_id`	The unique ID of the request. This is used in the Export Download Status request.
`status_url`	The URL of the export request.

Example Request & Response

Request (cURL)

Response (JSON)

curl --request POST \
     --url 'https://api2.branch.io/v2/analytics?organization_id={organization_id}&limit=5000&format=json' \
     --header 'Accept: application/json' \
     --header 'Access-Token: api_org_9999999999999999999999999999' \
     --header 'Content-Type: application/json' \
     --data '
{
     "start_date": "2021-12-12",
     "end_date": "2021-12-18",
     "data_source": "eo_install",
     "dimensions": [
          "user_data_os"
     ],
     "filters": {
          "attributed": "true",
          "user_data_os": [
              "IOS", 
              "ANDROID"
          ]
     },
     "enable_install_recalculation": true,
     "granularity": "day",
     "aggregation": "total_count"
}
'

{
    "code": 200,
    "job_id": "8a2514d5-9035-445f-b42a-948112aeb807",
    "status_url": "https://api2.branch.io/v2/analytics/a38bd2f0-9740-4334-8c96-5bfd90671b06"
}

Export Download Status

Request Info

Export Request

GET /v2/analytics/{job_id}
Host: api2.branch.io
Accept: application/json

Request Headers

Header	Description	Required
`Access-Token`	Key that encapsulates the user's permission with regards to an organization. Obtained from the Branch Dashboard. Needed for authentication.	Yes
`accept`	application/json	Recommended
`content-type`	application/json	Recommended

Request Path Parameters

Parameter	Description	Required
`job_id`	The unique ID of the request. Obtained from the Export Request	Yes

Request Query Parameters

Parameter	Description	Required
`organization_id` or `app_id`	Unique identifier for app/organization of requested data.	Yes
`limit`	The maximum number of results to return. Default: 50000 Min: 50000 Max: 50000 (unless a higher limit is specified)	No
`format`	Format of returned data. Defaults to CSV.	No

Response Info

Response Body Parameters

Parameter	Description
`code`	The response code.
`status`	The status of the original request by `job_id`.
`response_url`	The URL of your request for download.

Example Request & Response

Request (cURL)

Response (JSON)

curl --request GET \
     --url 'https://api2.branch.io/v2/analytics{job_id}?organization_id=787326553414456146&limit=5000&format=json' \
     --header 'Accept: application/json' \
     --header 'Access-Token: api_org_99999999999999999999'

{
    "code": 200,
    "status": "FINISHED",
    "response_url": "https://branch-exports.s3.amazonaws.com/partner-query/2021-12-12-2021-12-18-eo_install-day-8a2514d5-9035-445f-b42a-948112aeb807-j6zbNS9OxQOz7spz.json?Signature=gbEoMAFAr0y7kN3stZ1zzUh60ko%3D&AWSAccessKeyId=AKIAI7A6NRHGMRDK2LIQ&Expires=1648077926"
}

Appendix

Filters

Filters work based on AND at the top level. Each dimension can have multiple or filters e.g. { user_data_os": ["IOS", "ANDROID"] }.

Topics

[
  "eo_impression",
  "eo_click",
  "eo_branch_cta_view",
  "eo_sms_sent",
  "eo_open",
  "eo_install",
  "eo_reinstall",
  "eo_web_session_start",
  "eo_pageview",
  "eo_commerce_event",
  "eo_custom_event",
  "eo_content_event",
  "eo_dismissal",
  "eo_user_lifecycle_event",
  "cost",
  "skadnetwork-valid-messages",
  // Fraud topics:
  "eo_click_blocked",
  "eo_impression_blocked",
  "eo_install_blocked",
  "eo_reinstall_blocked",
  "eo_open_blocked",
  "eo_web_session_start_blocked",
  "eo_pageview_blocked",
  "eo_sms_sent_blocked",
  "eo_custom_event_blocked",
  "eo_content_event_blocked",
  "eo_commerce_event_blocked",
  "eo_user_lifecycle_event_blocked",
  "eo_branch_cta_view_blocked"
]

Dimensions

General Info

User Info

Last Attributed Touch

Last CTA View

SKAN

Other

[
  "name",
  "origin",
  "timestamp",
  "deep_linked",
  "from_desktop",
  "attributed"
]

[
  "user_data_app_store",
  "user_data_app_version",
  "user_data_os",
  "user_data_language",
  "user_data_platform",
  "user_data_environment",
  "user_data_geo_region_en",
  "user_data_geo_dma_code",
  "user_data_geo_country_code",
  "user_data_country",
  "user_data_cpp_level",
  "user_data_opted_in",
  "user_data_opted_in_status"
]

[
  "last_attributed_touch_type",
  "last_attributed_touch_data_tilde_tags",
  "last_attributed_touch_data_tilde_secondary_publisher",
  "last_attributed_touch_data_plus_current_feature",
  "last_attributed_touch_data_plus_via_features",
  "last_attributed_touch_data_tilde_campaign",
  "last_attributed_touch_data_tilde_advertising_partner_name",
  "last_attributed_touch_data_tilde_advertising_partner_id",
  "last_attributed_touch_data_tilde_feature",
  "last_attributed_touch_data_tilde_creative_name",
  "last_attributed_touch_data_plus_web_format",
  "last_attributed_touch_data_tilde_creative_id",
  "last_attributed_touch_data_tilde_ad_name",
  "last_attributed_touch_data_tilde_ad_id",
  "last_attributed_touch_data_tilde_campaign_id",
  "last_attributed_touch_data_tilde_placement",
  "last_attributed_touch_data_tilde_stage",
  "last_attributed_touch_data_tilde_channel",
  "last_attributed_touch_data_tilde_ad_set_name",
  "last_attributed_touch_data_tilde_ad_set_id",
  "last_attributed_touch_data_tilde_keyword",
  "last_attributed_touch_data_tilde_journey_id",
  "last_attributed_touch_data_tilde_view_name",
  "last_attributed_touch_data_tilde_view_id",
  "last_attributed_touch_data_tilde_agency",
  "last_attributed_touch_data_tilde_agency_id"
]

[
  "last_cta_view_data_tilde_ad_name",
  "last_cta_view_data_tilde_secondary_publisher",
  "last_cta_view_data_tilde_campaign",
  "last_cta_view_data_tilde_advertising_partner_name",
  "last_cta_view_data_tilde_feature",
  "last_cta_view_data_tilde_ad_set_name",
  "last_cta_view_data_tilde_ad_set_id",
  "last_cta_view_data_tilde_campaign_id",
  "last_cta_view_data_tilde_creative_name",
  "last_cta_view_data_tilde_creative_id",
  "last_cta_view_data_plus_via_features",
  "last_cta_view_data_dollar_3p",
  "last_cta_view_data_tilde_tags",
  "last_cta_view_data_plus_web_format",
  "last_cta_view_data_tilde_channel",
  "last_cta_view_data_tilde_ad_id",
  "last_cta_view_data_tilde_stage"
]

[
  "body_ad_network_id",
  "body_campaign_id",
  "body_app_id",
  "body_redownload",
  "body_source_app_id",
  "body_source_identifier",
  "body_conversion_value",
  "body_coarse_conversion_value",
  "body_last_attributed_touch_data_tilde_creative_name",
  "body_last_attributed_touch_data_tilde_ad_set_name",
  "body_last_attributed_touch_data_tilde_creative_id",
  "body_last_attributed_touch_data_tilde_ad_set_id",
  "body_last_attributed_touch_data_tilde_ad_name",
  "body_last_attributed_touch_data_tilde_ad_id",
  "body_last_attributed_touch_data_tilde_campaign_id",
  "body_last_attributed_touch_data_tilde_campaign_name",
  "annotation_dollar_3p",
  "annotation_conversion_value_mapped_value",
  "annotation_conversion_value_revision",
  "annotation_campaign_id_mapped_value",
  "annotation_campaign_id_revision",
  "annotation_source_app_id_mapped_value",
  "annotation_source_app_id_revision",
  "body_last_attributed_touch_data_tilde_campaign",
  "last_attributed_touch_data_tilde_creative_name",
  "last_attributed_touch_data_tilde_ad_set_name",
  "last_attributed_touch_data_tilde_creative_id",
  "last_attributed_touch_data_tilde_ad_set_id",
  "last_attributed_touch_data_tilde_ad_name",
  "last_attributed_touch_data_tilde_ad_id",
  "last_attributed_touch_data_tilde_campaign_id",
  "last_attributed_touch_data_tilde_campaign",
  "last_attributed_touch_data_tilde_agency",
  "last_attributed_touch_data_tilde_agency_id",
  "last_attributed_touch_data_tilde_advertising_partner_name",
  "last_attributed_touch_data_tilde_advertising_partner_id",
  "annotation_customer_event_alias"
]

[
  "days_from_last_attributed_touch_to_event",
  "days_from_last_cta_view_to_event",
  "event_data_product_categories",
  "event_data_custom_param_1",
  "event_data_custom_param_2",
  "event_data_custom_param_3",
  "first_event_for_user",
  "customer_event_alias"
]

Aggregate API Overview

Overview

Benefits

Limitations

Try It!

Getting Started

Prerequisites

Access

General Access

Agency Access

Authentication

Usage

Request Aggregate Export

Request Info

Response Info

Example Request & Response

Export Download Status

Request Info

Response Info

Example Request & Response

Appendix

Filters

Topics

Dimensions

Shortcuts

Company

Resources