βœ•
Filters
Submit a TicketBranch DashboardBranch University

Aggregate API

πŸ‘

Try it!

Try out the Aggregate API using your Branch data via the API Reference here.

Overview

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

Benefits of Branch Aggregate API

  • Give access to agencies and ad networks to pull aggregate data themselves.
    • Agencies and ad networks will only receive filtered data that they've been granted access to via user permissions.
  • Support for Facebook Marketing Partners (FMP) to have some visibility through aggregate data.

API Limitations

Limitation

Details

Max number of records returned by API

50,000
Branch may define dynamic record limits based on App/Org ID

Export Window

Rolling 2 year window

Max number of dimensions

11 Dimensions

Max number of measures

5 Measures

Max number of days that can be queried at a time

7 Days

Rate Limits

  • 2 requests per second
  • 5 requests per minute
  • 150 requests per hour

🚧

Cost/Click/Impression Data

SANs CCI (Cost / Click / Impression) data is not available for Aggregate API. You can use the Query API with xx_impression for getting the aggregated data of impressions for SANs.

Prerequisites & API Access

In order to use the Branch Aggregate API, you need to have completed the following:

  1. Created a Branch Dashboard
  2. Enabled Universal Ads and are already running ad campaigns for your Branch account.
  3. Implemented the Branch SDK into your mobile app (iOS | Android)
  4. Logged into the Branch Dashboard with the Aggregate Data Permission enabled.

Providing Agencies 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 Branch Aggregate data.

To provide an agency team member with access to the Aggregate 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.
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 Branch Aggregate API require an api_key query string parameter to be passed with each request. API Keys are generated on per-user bases and are permanent.

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

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

API Usage

Export Request

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

Request Headers:

HeaderDescriptionRequired
Access-TokenKey that encapsulates the users permission w.r.t an org. Obtained from the Branch Dashboard needed for authentication.Yes

Request Query Parameters:

ParameterDescriptionRequired
organization_id or app_idUnique identifier for app/organization of requested data.Yes
limitThe maximum number of results to return.Default: 50000
Min: 50000
Max: 50000 (unless a higher limit is specified)		No
formatFormat 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 for complete list.

Yes

dimensions

An array representing dimension(s) to group by.

Limit is 11.

See Dimensions 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

  • "day"
  • "week"
  • "month"

The time granularity that each band value will represent.

Default: day

Note: Do not add timestamp to dimensions field when setting granularity to day. Instead, add name to the dimensions field.

No

aggregation

  • "unique_count"
  • "total_count"
  • "revenue"
  • "cost"
  • "cost-in-local-currency"

How to count events towards the final result count.

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.

Default: total_count

No
enable_install_calculationIf 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: falseNo

Response Body Parameters

ParameterDescription
codeThe response code
job_idThe unique ID of the request. This is used in the Export Download Status request.
status_urlThe URL of the export request.

Example Request/Response:

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

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

Request Headers:

HeaderDescriptionRequired
Access-TokenKey that encapsulates the users permission w.r.t an org. Obtained from the Branch Dashboard.Yes

Response Path Parameters

ParameterDescriptionRequired
job_idThe unique ID of the request.Obtained from the Export RequestYes

Request Query Parameters:

ParameterDescriptionRequired
organization_id or app_idUnique identifier for app/organization of requested data.Yes
limitThe maximum number of results to return.Default: 50000
Min: 50000
Max: 50000 (unless a higher limit is specified)		No
formatFormat of returned data. Defaults to csv.No

Response Body Parameters

ParameterDescription
codeThe response code
statusThe status of the original request by job_id
response_urlThe URL of your request for download.

Example Request/Response:

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

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

[
  "user_data_app_store",
  "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_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"
]