Request Aggregate Export

  • Published on Feb 25, 2025
Post
/analytics

By passing in the appropriate options, you can initiate an export of your aggregate Branch data.

Security
API Key
Query parameter nameapp_id

app_id | Unique identifier for Branch app of requested data.

API Key
Header parameter nameAccess-Token

Access-Token | Key that encapsulates the users permission w.r.t an org. Obtained from the Branch Dashboard needed for authentication.

Query parameters
limit
integer (int32)

The maximum number of results to return.

Minimum1
Maximum50000
format
string

Format of returned data. json or csv

Valid values[ "csv", "json" ]
Default"csv"
Body parameters
Expand All
object
start_date
string (date) Required

The start of the interval time range represented as an ISO-8601 complete date.

Example2023-05-15
end_date
string (date) Required

The end of the interval time range represented as an ISO-8601 complete date.

Example2023-05-16
data_source
string Required

A string value representing the data source. See Topics for complete list.

Valid values[ "eo_impression", "eo_click", "eo_web_to_app_auto_redirect", "eo_branch_cta_view", "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", "eo_click_blocked", "eo_impression_blocked", "eo_install_blocked", "eo_reinstall_blocked", "eo_open_blocked", "eo_web_session_start_blocked", "eo_pageview_blocked", "eo_custom_event_blocked", "eo_content_event_blocked", "eo_commerce_event_blocked", "eo_user_lifecycle_event_blocked", "eo_branch_cta_view_blocked", "eo_web_to_app_auto_redirect_blocked" ]
Default"eo_install"
dimensions
Array of string Required

An array representing dimension(s) to group by. Limit is 11. See Dimensions for complete list.

Min items1
Max items11
Default[ "name" ]
Example[ "user_data_os" ]
string
Valid values[ "name", "app_id", "app_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_dma_code", "user_data_geo_country_code", "user_data_country", "user_data_cpp_level", "user_data_geo_region_en", "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_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_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_keyword_id", "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_attributed_touch_data_tilde_customer_secondary_publisher", "last_attributed_touch_data_tilde_customer_ad_set_name", "last_attributed_touch_data_tilde_customer_ad_name", "last_attributed_touch_data_tilde_customer_keyword", "last_attributed_touch_data_tilde_customer_placement", "last_attributed_touch_data_tilde_customer_sub_site_name", "last_attributed_touch_data_tilde_customer_campaign", "last_attributed_touch_data_plus_web_format", "last_attributed_touch_data_plus_current_feature", "last_attributed_touch_data_plus_via_features", "last_attributed_touch_data_dollar_marketing_title", "last_attributed_touch_data_dollar_3p", "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_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", "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", "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" ]
granularity
string

The time granularity that each band value will represent.

Valid values[ "day", "week", "month" ]
Default"day"
aggregation
string

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.

Valid values[ "unique_count", "total_count", "revenue", "cost", "cost-in-local-currency" ]
Default"total_count"
enable_install_calculation
boolean

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

Defaultfalse
filters
object (analytics_body_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.

Example{ "attributed": true, "user_data_os": [ "IOS", "ANDROID" ] }
name
Array of string

The name of the event, such as "CLICK", "INSTALL", "PURCHASE" or custom event names like "UpdateSettings". Set either by the client (e.g. custom events) or automatically server side. See events for Standard Events enum.

string
ExampleINSTALL
app_id
Array of string

Unique identifier for Branch app of requested data.

string
Example0000000
app_name
Array of string

The name of your Branch App

string
ExampleMyApp
origin
Array of string

Whether the event originated with a Branch SDK/API call, or was sent by Segment or mParticle. Set automatically server side.

string
Valid values[ "BRANCH", "SEGMENT", "MPARTICLE" ]
timestamp
Array of string

Unix timestamp in milliseconds for the event. Set automatically server side.

string
Example1651159080
deep_linked
Array of string

True if the current app or web session resulted in the user being deep linked. Set automatically server side.

string
Valid values[ "True", "False" ]
from_desktop
Array of string

True if the last attributed touch originated on desktop and the user continued through to mobile via Text Me The App. Set automatically server side.

string
Valid values[ "True", "False" ]
attributed
Array of string

Whether the event is attributed. This will always be accompanied by last_attributed_touch_type and last_attributed_touch_data. Set automatically server side.

string
Valid values[ "True", "False" ]
user_data_os
Array of string

Operating System (OS) of the device where the event occurred. Note that robots include web and app robots for easy filtering. Specified by the client.

string
Valid values[ "AMAZON_FIRE", "AMAZON_FIRE_TV", "ANDROID", "BADA", "BEOS", "BLACKBERRY", "BSD", "CENTOS", "CHROMIUM_OS", "DEBIAN", "DRAGONFLY", "FEDORA", "FIREFOX_OS", "FREEBSD", "GENTOO", "GNU", "IOS", "JOLI", "KUBUNTU", "LINUX", "MAC_OS", "MANDRIVA", "MEEGO", "MINT", "NETBSD", "NINTENDO", "OPENBSD", "OS_2", "OTHER", "PLAYSTATION", "RIM_TABLET_OS", "ROBOTS", "SAILFISH", "SLACKWARE", "SOLARIS", "SUSE", "SYMBIAN", "TIZEN", "TVOS", "UBUNTU", "UNIX", "WINDOWS", "WINDOWS_PHONE", "ZENWALK", "ROKU", "SAMSUNG", "ANDROID_TV", "LG", "PANASONIC" ]
user_data_language
Array of string

Language specified in the user_agent string (or in some cases other headers), Specified by the client.

string
user_data_platform
Array of string

Convenience dimension that allows users to easily see web vs app, desktop vs mobile, and iOS vs Android vs other. Derived from information specified by the client.

string
user_data_environment
Array of string

Runtime environment where the event occurred, which can distinguish between e.g. full app vs instant app. Specified by the client.

string
Valid values[ "FULL_WEB", "FULL_APP", "IMESSAGE_APP", "INSTANT_APP", "TV_WEB", "TV_APP", "APP_CLIP" ]
user_data_geo_dma_code
Array of string

DMA code, derived from IP address. https://support.google.com/richmedia/answer/2745487?hl=en. Set automatically server side.

string
user_data_geo_country_code
Array of string

Country code, derived from IP address. Set automatically server side.

string
user_data_country
Array of string

Country, derived from user agent string or request body field. Specified by the client.

string
user_data_cpp_level
Array of string

Consumer Protection Preference level.

string
user_data_geo_region_en
Array of string

Human-readable region, derived from IP address. Set automatically server side.

string
user_data_opted_in
Array of string

Boolean for whether the second OPEN can be infered as INSTALL after opt-in. If set, the event can be considered as our synthetic OPEN generated by api-open by inspecting incoming event paramters with persona data. If the event is not considered as the second OPEN, the flag is not present. Only available for iOS14.5 or higher

string
Valid values[ "True", "False" ]
user_data_opted_in_status
Array of string

Current authorization status of opt-in flag for iOS14.5 or higher traffic. The flag is sent directly from the SDK.

string
last_attributed_touch_type
Array of string

Whether the last attributed touch was an impression, a click, or a web to app auto redirect. Set automatically server side.

string
Valid values[ "CLICK", "WEB_TO_APP_AUTO_REDIRECT", "IMPRESSION" ]
last_attributed_touch_data_tilde_campaign
Array of string

Campaign (name) specified for the last attributed touch. Can be specified on links by the client, or prefilled automatically server side in some cases.

string
last_attributed_touch_data_tilde_campaign_id
Array of string

Campaign ID specified for the last attributed touch. Set automatically server side.

string
last_attributed_touch_data_tilde_channel
Array of string

Channel specified for the last attributed touch. Can be specified on links by the client, or prefilled automatically server side in some cases.

string
last_attributed_touch_data_tilde_feature
Array of string

Feature specified for the last attributed touch. Can be specified on links by the client, or prefilled automatically server side in some cases.

string
last_attributed_touch_data_tilde_stage
Array of string

Stage specified for the last attributed touch. Can be specified on links by the client, or prefilled automatically server side in some cases.

string
last_attributed_touch_data_tilde_tags
Array of string

Tags specified for the last attributed touch. Can be specified on links by the client, or prefilled automatically server side in some cases.

string
last_attributed_touch_data_tilde_advertising_partner_name
Array of string

Human-readable advertising partner name specified for the last attributed touch. Set automatically server side.

string
last_attributed_touch_data_tilde_advertising_partner_id
Array of string

ID for the advertising partner specified for the last attributed touch. Set automatically server side OR specified by the client, for now, specific to partners migrating from TUNE.

string
last_attributed_touch_data_tilde_secondary_publisher
Array of string

Secondary publisher specified for the last attributed touch. Passed by the ad network.

string
last_attributed_touch_data_tilde_creative_name
Array of string

Creative name specified for the last attributed touch. Set automatically server side.

string
last_attributed_touch_data_tilde_creative_id
Array of string

Creative ID specified for the last attributed touch. Set automatically server side.

string
last_attributed_touch_data_tilde_ad_set_name
Array of string

Ad set name specified for the last attributed touch. Set automatically server side.

string
last_attributed_touch_data_tilde_ad_set_id
Array of string

Ad set ID specified for the last attributed touch. Set automatically server side.

string
last_attributed_touch_data_tilde_ad_name
Array of string

Ad name specified for the last attributed touch. Set automatically server side.

string
last_attributed_touch_data_tilde_ad_id
Array of string

Ad ID specified for the last attributed touch. Set automatically server side.

string
last_attributed_touch_data_tilde_keyword
Array of string

Keyword specified for the last attributed touch. Set automatically server side.

string
last_attributed_touch_data_tilde_keyword_id
Array of string

Keyword ID for the last attributed touch. Set automatically server side.

string
last_attributed_touch_data_tilde_placement
Array of string

Placement of the last touch, as set with an analytics tag. Actual app or website the ad appears on display campaigns.

string
last_attributed_touch_data_tilde_agency
Array of string

Agency of the last touch, as set with an analytics tag. Agency that runs ad campaigns on behalf of advertiser.

string
last_attributed_touch_data_tilde_agency_id
Array of string

ID of agency of the last touch, as set with an analytics tag. Agency that runs ad campaigns on behalf of advertiser.

string
last_attributed_touch_data_tilde_customer_secondary_publisher
Array of string

Customer secondary publisher.

string
last_attributed_touch_data_tilde_customer_ad_set_name
Array of string

Customer ad set name.

string
last_attributed_touch_data_tilde_customer_ad_name
Array of string

Customer ad name.

string
last_attributed_touch_data_tilde_customer_keyword
Array of string

Customer keyword.

string
last_attributed_touch_data_tilde_customer_placement
Array of string

Customer placement.

string
last_attributed_touch_data_tilde_customer_sub_site_name
Array of string

Customer sub site name.

string
last_attributed_touch_data_tilde_customer_campaign
Array of string

Customer campaign.

string
last_attributed_touch_data_dollar_marketing_title
Array of string

Marketing title of the Branch Link.

string
last_attributed_touch_data_dollar_3p
Array of string

The third party that was part of the last touch.

string
last_attributed_touch_data_plus_current_feature
Array of string

Branch feature (determined by Branch) of the current touch. Set automatically server side.

string
Valid values[ "EMAIL", "ADS", "DESKTOP_JOURNEYS", "MOBILE_JOURNEYS", "DESKTOP_DEEPVIEWS", "MOBILE_DEEPVIEWS", "SOCIAL", "QUICK_LINKS", "APP_CLIP" ]
last_attributed_touch_data_plus_via_features
Array of string

All Branch features (determined by Branch) which were determined, via attribution, to have led to this event. For example, if an email link click leads to a Journey which leads to the app, the published eo_open will have +via_features: [EMAIL, JOURNEYS]. set automatically server side.

string
Valid values[ "EMAIL", "ADS", "DESKTOP_JOURNEYS", "MOBILE_JOURNEYS", "DESKTOP_DEEPVIEWS", "MOBILE_DEEPVIEWS", "SOCIAL", "QUICK_LINKS", "APP_CLIP" ]
last_attributed_touch_data_plus_web_format
Array of string

Set if an event originated with a touch on Google AMP or Facebook Instant Article. Specified by the client.

string
Valid values[ "AMP", "INSTANT_ARTICLES" ]
last_attributed_touch_data_tilde_journey_id
Array of string

Audience rule id for a Journey. Set automatically server side.

string
last_attributed_touch_data_tilde_view_name
Array of string

"View Name" or "title" for a branch view / template. Can be specified on links by the client, or prefilled automatically server side in some cases.

string
last_attributed_touch_data_tilde_view_id
Array of string

Branch View ID for a Journey. Set automatically server side.

string
last_cta_view_data_tilde_campaign
Array of string

Campaign (name) specified for the last Branch CTA view. Can be specified on links by the client, or prefilled automatically server side in some cases.

string
last_cta_view_data_tilde_campaign_id
Array of string

Campaign id specified for the last Branch CTA view. Set automatically server side.

string
last_cta_view_data_tilde_channel
Array of string

Channel specified for the last Branch CTA view. Can be specified on links by the client, or prefilled automatically server side in some cases.

string
last_cta_view_data_tilde_feature
Array of string

Feature specified for the last Branch CTA view. Can be specified on links by the client, or prefilled automatically server side in some cases.

string
last_cta_view_data_tilde_stage
Array of string

Stage specified for the last Branch CTA view. Can be specified on links by the client, or prefilled automatically server side in some cases.

string
last_cta_view_data_tilde_tags
Array of string

Tags specified for the last Branch CTA view. Can be specified on links by the client, or prefilled automatically server side in some cases.

string
last_cta_view_data_tilde_advertising_partner_name
Array of string

Human-readable advertising partner name specified for the last Branch CTA view. Set automatically server side.

string
last_cta_view_data_tilde_secondary_publisher
Array of string

Secondary publisher specified for the last Branch CTA view. Passed by the ad network.

string
last_cta_view_data_tilde_creative_name
Array of string

Creative name specified for the last Branch CTA view. Set automatically server side.

string
last_cta_view_data_tilde_creative_id
Array of string

Creative ID specified for the last Branch CTA view. Set automatically server side.

string
last_cta_view_data_tilde_ad_set_name
Array of string

Ad set name specified for the last Branch CTA view. Set automatically server side.

string
last_cta_view_data_tilde_ad_set_id
Array of string

Ad Set ID specified for the last Branch CTA view. Set automatically server side.

string
last_cta_view_data_tilde_ad_name
Array of string

Ad name specified for the last Branch CTA view. Set automatically server side.

string
last_cta_view_data_tilde_ad_id
Array of string

Ad ID specified for the last Branch CTA view. Set automatically server side.

string
last_cta_view_data_plus_via_features
Array of string

All Branch features (determined by Branch) which were determined, via attribution, to have led to this event. For example, if an email link click leads to a Journeys CTA view, the published eo_branch_cta_view will have +via_features: [EMAIL, JOURNEYS]. set automatically server side.

string
Valid values[ "EMAIL", "ADS", "DESKTOP", "JOURNEYS", "MOBILE_JOURNEYS", "DESKTOP_DEEPVIEWS", "MOBILE_DEEPVIEWS", "SOCIAL", "QUICK_LINKS" ]
last_cta_view_data_dollar_3p
Array of string

Advertising partner short-code (e.g. e_rs) specified for the last Branch CTA view. Specified by the client.

string
last_cta_view_data_plus_web_format
Array of string

Set if an event originated with a Branch CTA view on Google AMP or Facebook Instant Article. Specified by the client.

string
body_ad_network_id
Array of string

SKAdNetwork ad network ID. Set server side.

string
body_campaign_id
Array of string

SKAdNetwork campaign ID. Set server side.

string
body_app_id
Array of string

SKAdNetwork App ID. Set server side.

string
body_redownload
Array of string

SKAdNetwork redownload status. Set server side.

string
body_source_app_id
Array of string

SKAdNetwork source app ID. Set server side.

string
body_conversion_value
Array of string

SKAdNetwork conversion value. Set server side.

string
body_last_attributed_touch_data_tilde_creative_name
Array of string

SKAdNetwork LATD creative name. Set server side.

string
body_last_attributed_touch_data_tilde_ad_set_name
Array of string

SKAdNetwork LATD ad set name. Set server side.

string
body_last_attributed_touch_data_tilde_creative_id
Array of string

SKAdNetwork LATD creative ID. Set server side.

string
body_last_attributed_touch_data_tilde_ad_set_id
Array of string

SKAdNetwork LATD ad set ID. Set server side.

string
body_last_attributed_touch_data_tilde_ad_name
Array of string

SKAdNetwork LATD ad name. Set server side.

string
body_last_attributed_touch_data_tilde_ad_id
Array of string

SKAdNetwork LATD ad iD. Set server side.

string
body_last_attributed_touch_data_tilde_campaign_id
Array of string

SKAdNetwork LATD campaign ID. Set server side.

string
body_last_attributed_touch_data_tilde_campaign_name
Array of string

SKAdNetwork LATD campaign name. Set server side.

string
body_last_attributed_touch_data_tilde_campaign
Array of string

SKAdNetwork LATD campaign. Set server side.

string
annotation_dollar_3p
Array of string

SKAdNetwork annotation 3p shortcode. Set server side.

string
annotation_conversion_value_mapped_value
Array of string

SKAdNetwork annotation conversion value mapped value. Set server side.

string
annotation_conversion_value_revision
Array of string

SKAdNetwork annotation conversion value revision. Set server side.

string
annotation_campaign_id_mapped_value
Array of string

SKAdNetwork annotation campaign ID mapped value. Set server side.

string
annotation_campaign_id_revision
Array of string

SKAdNetwork annotation campaign ID revision. Set server side.

string
annotation_source_app_id_mapped_value
Array of string

SKAdNetwork annotation source app ID mapped value. Set server side.

string
annotation_source_app_id_revision
Array of string

SKAdNetwork annotation source app ID. Set server side.

string
annotation_customer_event_alias
Array of string

SKAdNetwork annotation customer event alias. Set server side.

string
days_from_last_attributed_touch_to_event
Array of string

Number of days between when the last touch occurred and when this event subsequently occurred. Set automatically server side.

string
Pattern\d
days_from_last_cta_view_to_event
Array of string

Number of days between when the last Branch CTA view occurred and when this event subsequently occurred. sSet automatically server side.

string
Pattern\d
event_data_product_categories
Array of string

Iterate over content_items and aggregate the category from each product. Specified by the client.

string
Valid values[ "ANIMALS_AND_PET_SUPPLIES", "APPAREL_AND_ACCESSORIES", "ARTS_AND_ENTERTAINMENT", "BABY_AND_TODDLER", "BUSINESS_AND_INDUSTRIAL", "CAMERAS_AND_OPTICS", "ELECTRONICS", "FOOD_BEVERAGES_AND_TOBACCO", "FURNITURE", "HARDWARE", "HEALTH_AND_BEAUTY", "HOME_AND_GARDEN", "LUGGAGE_AND_BAGS", "MATURE", "MEDIA", "OFFICE_SUPPLIES", "RELIGIOUS_AND_CEREMONIAL", "SOFTWARE", "SPORTING_GOODS", "TOYS_AND_GAMES", "VEHICLES_AND_PARTS" ]
first_event_for_user
Array of string

If this is the first time for this persona that this event has been triggered. Set automatically server side.

string
Valid values[ "True", "False" ]
customer_event_alias
Array of string

Customers can specify that an event of type "purchase" should have name "buy20tokens". customer_event_alias captures this name, which is additional information. For most events this is likely unnecessary.

string
Responses
200

Status of aggregate export

Result
"{\n  \"code\": 200,\n  \"job_id\": \"XXXX-0000-xxxx\",\n  \"status_url\": \"https://api2.branch.io/v2/analytics/{JOB_ID_HERE}\"\n}"
object
code
integer
Example200
job_id
string

The unique ID of the request. This is used in the Export Download Status request.

ExampleXXXX-0000-xxxx
status_url
string

The URL of the export request.

Examplehttps://api2.branch.io/v2/analytics/{JOB_ID_HERE}
400

Authentication Failed

Result
"{\n    \"error\": {\n        \"message\": \"Authentication failed !\",\n        \"code\": 400\n    }\n}"
Expand All
object
error
object (inline_response_400_error)
message
string
ExampleAuthentication failed !
code
integer
Example400
500

Internal Server Error

Result
"{\n    \"error\": {\n        \"message\": \"Our product is failing to serve your request at this moment. Please try again later.\",\n        \"code\": 500\n    }\n}"
Expand All
object
error
object (inline_response_500_error)
message
string
ExampleInternal Server Error
code
integer
Example500