Search specific term/phrase surrounded by double quotes. e.g. “deep linking”
Exclude records that contain a specific term prefixed with a minus. e.g. Android -Firebase

👍

Try it!

Try out the Custom Exports API using your Branch data via the API reference here

Overview

Benefits of Custom Exports API

  • The Branch Custom Exports find and queue log records that match your search criteria for export. You can do so either via the Custom Exports section in your Branch Dashboard or via the API (this page).

API Limitations

Limitation

Details

Data Availability

The data will be available around 2-3 hours behind real-time

Max number of records returned by API

If you want to limit the number of records returned to 2 million or less, do so using the limit parameter.

If you need more than 2 million records returned, use the allow_multiple_files parameter instead and set it to true.

Max number of days that can be queried at a time

60

Rate Limit for creating exports*

  • 10 requests per minute
  • 25 requests per hour

Rate Limit for checking the status of a report*

  • 50 requests per minute
  • 1000 requests per hour
Exporting from test environmentsAt this moment, it is not possible to export data out of a Branch Test environment
Repeated requests within 60 minutes will be cachedIf you make identical requests within 60 minutes of each other, you will not see multiple export jobs running. Instead, the same export job will be used. If you are using the API, the same job_id will be returned. This is to avoid the case of hundreds or thousands of requests being made for the exact same data set, within seconds or minutes of each other.After 60 minutes, your request will kick off a new job to retrieve data.

You will get the following response once you've hit the rate limit:

{
    "errors": [
        {
            "message": "Limit is exceeded for org-525983469347282987, retry after 3418 seconds",
            "error_code": 7
        }
    ]
}

Prerequisites & API Access

In order to use the Custom Exports API, you need to have completed the following:

  1. Created a Branch Dashboard
  2. Implemented the Branch SDK into your mobile app (iOS | Android)
  3. Opt into sharing 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.

🚧

Data Changes Post iOS

Opt-ins will affect your final install count. We recommend using a different identifier (ex. IDFV) to de-dupe install events on your internal systems.

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

  1. Logged into the Branch Dashboard with the Sensitive Data and Export Access Permission enabled.

Providing Agencies API 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.

🚧

Data Purge

  • Branch will purge last-attributed data after 60 days.

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 Configure, 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 Sensitive 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 sensitive data associated with all of your campaigns, regardless if they are associated with them or not.

Authentication

Calls to the Custom Export API require an access token parameter to be passed with each request. Access tokens are generated on a per-user basis and are permanent.

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

API Usage

Create Export Request

POST /v2/logs?organization_id=ORG_ID
POST /v2/logs?app_id=APP_ID
Headers:
Access-Token: API_KEY
Content-Type: application/json
Body: JSON parameters
Host: api2.branch.io

Request Headers

HeaderDescriptionRequired
Access-TokenKey that encapsulates the user's permission w.r.t an org. Obtained from the Branch Dashboard needed for authentication.Yes
Content-Typeapplication/jsonYes

Request Body Parameters

ParameterTypeDescriptionRequired
start_dateDateThe beginning datetime for the requested results, provided in ISO-8601 format including Hours, Minutes, Seconds and Milliseconds.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:00ZYes
end_dateDateThe end datetime for the requested results, provided in ISO-8601 format including Hours, Minutes, Seconds and Milliseconds.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:59:999ZYes
report_typeStringThe Branch EO topic to be exported.Yes
fieldsComma Separated ListList of comma-separated fields desired in results.Yes
limitIntegerIf you want to limit the number of records returned to 2 million or less, do so using this parameter by passing an integer representing the number of records you want returned.

If you need more than 2 million records returned, use the allow_multiple_files parameter instead.
Yes
timezoneStringTimezone for results. Accepts tz database strings like ‘America/Los_Angeles’.Optional parameter; results are returned in the dashboard timezone if not provided. Will default to UTC only if dashboard timezone is not set.No
filterComma Separated ListFilter by fields and boolean operators against fields of the LogInstalls model; must be URI encoded and JSON parsed. Example: ["gt","last_attributed_touch_timestamp", 1604015756]No
response_formatStringFormat of the response; can be either "json" or "csv". If not selected, defaults to CSV. Branch uses UTF-8 encoding for CSV files.No
allow_multiple_filesBooleanSet this parameter to true if you want more than 2 million records returned. Branch will make the records available to you in multiple files.No
response_format_compressionStringThe file compression method to use for the data.

Options:
- gz
- snappy
Yes if you set allow_multiple_files to true

Response Body Parameters

ParameterDescription
handleUnique request handle generated against the endpoint call.
export_job_status_urlThe URL of the export request.

Example Request/Response

curl -X POST 'https://api2.branch.io/v2/logs?app_id=123456700098765432'
	-H "Content-Type: application/json"
	-H "Access-Token: YOUR_ACCESS_TOKEN_HERE"
	-d '{"report_type": "eo_open",
			"limit": 100,
			"fields": ["timestamp","name"],
			"start_date": "2019-12-09T00:00:00Z",
			"end_date": "2019-12-09T01:59:59Z",
			"filter": ["gt","last_attributed_touch_timestamp", 1604015756]
			}'
{"handle":"1612dbb3-85ef-49f8-b1c5-5818c163600c","export_job_status_url":"https://api2.branch.io/v2/logs/1612dbb3-85ef-49f8-b1c5-5818c163600c?app_id=123456700098765432"}

Response Codes

Response CodeDescription
200Status of aggregate export.
400Authentication Failed.

Get Export Request

GET /v2/logs/JOB_ID
Headers:
Access-Token: API_KEY
Host: api2.branch.io

Request Headers

HeaderDescriptionRequired
Access-TokenKey that encapsulates the user's permission w.r.t an org. Obtained from the Branch Dashboard needed for authentication.Yes
Content-Typeapplication/jsonYes

Response Path Parameters

ParameterTypeDescriptionRequired
request_handleStringThe ID returned by the log export queue.Yes

Request Query Parameters

ParameterTypeDescriptionRequired
limitIntegerThe maximum number of results to return.No
formatStringFormat of returned data. json or csvNo

Response Body Parameters

ParameterTypeDescription
codeIntegerThe response code.
lines_exportedIntegerNumber of lines exported against the originated request.
statusStringRequest status over the current execution time.
status_urlStringThe URL of the export request.

Example Request/Response

curl -X GET https://api2.branch.io/v2/logs/<YOUR_HANDLE>\?app_id\=<YOUR_BRANCH_APP_ID>
  -H "Content-Type: application/json" 
  -H "Access-Token:<YOUR_ACCESS_TOKEN>"
{"code":200,"lines_exported":2000000,"status":"complete","response_url":"https://branch-exports-web.s3.amazonaws.com/732662944269095814-eo_open-2019-12-10-2019-12-10-1612dbb3-85ef-49f8-b1c5-5818c163600c-bUlN2lwyTE10qIVH.csv?Signature=YOUR_ACCESS_TOKEN_HERE&AWSAccessKeyId=YOUR_ACCESS_TOKEN_HERE&Expires=1577305615"}

Response Codes

Response CodeDescription
200Status of aggregate export
400Authentication Failed
404Job ID Not Found

Status Values

StatusDescription
pendingRequest is pending.
runningRequest is still running.
completeRequest is complete.
failRequest failed.

Check Data Readiness

POST /v2/data/ready
Headers:
Access-Token: YOUR_API_KEY_HERE
Content-Type: application/json
Body: JSON parameters
Host: api2.branch.io

Request Headers

HeaderDescriptionRequired
Access-TokenKey that encapsulates the user's permissions with regard to an org. Obtained from the Branch Dashboard and needed for authentication.Yes
Content-Typeapplication/jsonYes

Request Body Parameters

ParameterTypeDescriptionRequired
dateStringThe start of the interval time range, in the format YYYY-MM-DD hh:mm:ss (must be within the past year).Yes
warehouse_meta_typeStringThe type of data to check for. Can be either EVENT or AGGREGATE.Yes
topicStringThe Branch EO topic to be exported.Yes
app_idIntegerYour Branch App ID, found under Account Settings in your Branch Dashboard.Yes

Response Body Parameters

ParameterDescription
data_readyWhether or not the requested data is ready; can be true or false.
dateThe date and time associated with the requested data, in the format YYYY-MM-DD hh:mm:ss.

Examples

Successful Request/Response:

curl -X POST 'http://api2.branch.io/v2/data/ready'
	-H 'Content-Type: application/json' 
	-H 'Accept: application/json'
	-H 'Access-Token: <YOUR_API_KEY_HERE>'
	-d '{"date":"2024-01-05 17:00:00",
		"warehouse_meta_type":"EVENT",
		"topic":"eo_click",
		"app_id":"<YOUR_APP_ID_HERE>"}'
{ "data_ready": true, "date": "2024-01-05 17:00:00" }

Invalid Request/Response:

curl -X POST 'http://api2.branch.io/v2/data/ready'
	-H 'Content-Type: application/json' 
	-H 'Accept: application/json'
	-H 'Access-Token: <YOUR_API_KEY_HERE>'
	-d '{"date":"2024-01-06 17:00:00",
		"warehouse_meta_type":"EVENT",
		"topic":"eo",
		"app_id":"<YOUR_APP_ID_HERE>"}'
{"errors":[{"message":"Report type eo is invalid. It has to be one of: [eo_branch_cta_view, eo_click, eo_commerce_event, eo_content_event, eo_custom_event, eo_impression, eo_install, eo_open, eo_pageview, eo_reinstall, eo_user_lifecycle_event, eo_web_session_start, eo_web_to_app_auto_redirect, eo_dismissal, eo_san_touch, webhook2, skadnetwork_invalid_messages, skadnetwork_valid_messages, eo_branch_cta_view_blocked, eo_click_blocked, eo_commerce_event_blocked, eo_content_event_blocked, eo_custom_event_blocked, eo_impression_blocked, eo_install_blocked, eo_open_blocked, eo_pageview_blocked, eo_reinstall_blocked, eo_user_lifecycle_event_blocked, eo_web_session_start_blocked]","error_code":7}]}

Response Codes

Response CodeDescription
200Status of data successfully retrieved.
400Topic is invalid or data retention for requested data has expired.
500Internal server error (Branch failure).

Appendix

Available EO Fields

FieldsTypeDescription
app_idLongApp ID (capitalize ID in Liveview)
app_nameStringApp Name
attributedBooleanAttributed
content_itemsArrayStructContent Items
custom_dataMapStringStringCustom Data
customer_event_aliasStringCustomer Event Alias
days_from_last_attributed_touch_to_eventIntegerDays From Last Attributed Touch To Event
deep_linkedBooleanDeep Linked
di_match_click_tokenLongDI Match Click Token
event_data_ad_typeenum { BANNER, INTERSTITIAL, REWARDED_VIDEO, NATIVE }Ad Type
event_data_affiliationStringAffiliation
event_data_couponStringCoupon
event_data_currencyStringCurrency
event_data_descriptionStringEvent Description
event_data_exchange_rateDoubleExchange Rate
event_data_revenueDoubleRevenue
event_data_revenue_in_usdDoubleRevenue In USD
event_data_search_queryStringSearch Query
event_data_shippingDoubleShipping
event_data_taxDoubleTax
event_data_transaction_idStringTransaction ID
event_data_local_currencyStringLocal Currency
event_data_local_currency_exchange_rateStringLocal Currency Exchange Rate
event_data_revenue_in_local_currencyStringRevenue in Local Currency
event_data_custom_param_1StringCustom parameter for event
event_data_custom_param_2StringCustom parameter for event
event_data_custom_param_3StringCustom parameter for event
event_timestampLongEvent Timestamp
existing_userBooleanExisting User
external_intent_uriStringExternal Intent URI
first_event_for_userBooleanFirst Event For User
hash_versionStringHash Version
hours_from_last_attributed_touch_to_eventIntegerHouse From Last Attributed Touch To Event
idStringID
install_activity_attributedBooleanInstall Attributed
install_activity_data_has_clicked_adBooleanInstall Has Clicked Ad
install_activity_data_has_clicked_emailBooleanInstall Has Clicked Email
install_activity_timestampLongInstall Timestamp
install_activity_touch_data_additional_data_tilde_ad_idLongInstall Ad ID
install_activity_touch_data_additional_data_tilde_ad_set_idLongInstall Ad Set ID
install_activity_touch_data_additional_data_tilde_campaign_idLongInstall Campaign ID
install_activity_touch_data_additional_data_tilde_creative_idLongInstall Creative ID
install_activity_touch_data_dollar_3pStringInstall Partner 3p Value
install_activity_touch_data_plus_via_featuresStringInstall Features
install_activity_touch_data_plus_web_formatStringInstall Web Format
install_activity_touch_data_tilde_ad_nameStringInstall Ad Name
install_activity_touch_data_tilde_ad_set_nameStringInstall Ad Set Name
install_activity_touch_data_tilde_advertising_partner_idLongInstall Ad Partner ID
install_activity_touch_data_tilde_advertising_partner_nameStringInstall Ad Partner
install_activity_touch_data_tilde_agencyStringInstall Agency
install_activity_touch_data_tilde_agency_idLongInstall Agency ID
install_activity_touch_data_tilde_campaignStringInstall Campaign
install_activity_touch_data_tilde_channelStringInstall Channel
install_activity_touch_data_tilde_creative_nameStringInstall Creative Name
install_activity_touch_data_tilde_customer_ad_nameStringInstall Customer Ad Name
install_activity_touch_data_tilde_customer_ad_set_nameStringInstall Customer Ad Set Name
install_activity_touch_data_tilde_customer_campaignStringInstall Customer Campaign
install_activity_touch_data_tilde_customer_keywordStringInstall Customer Keyword
install_activity_touch_data_tilde_customer_placementStringInstall Customer Placement
install_activity_touch_data_tilde_customer_secondary_publisherStringInstall Customer Secondary Publisher
install_activity_touch_data_tilde_customer_sub_site_nameStringInstall Customer Sub Site Name
install_activity_touch_data_tilde_featureStringInstall Feature
install_activity_touch_data_tilde_journey_nameStringInstall Journey Name
install_activity_touch_data_tilde_keywordStringInstall Keyword
install_activity_touch_data_tilde_placementStringInstall Placement
install_activity_touch_data_tilde_secondary_publisherStringInstall Secondary Publisher
install_activity_touch_data_tilde_stageStringInstall Stage
install_activity_touch_data_tilde_tagsStringInstall Tags
install_activity_touch_data_tilde_view_nameStringInstall View Name`
install_activity_touch_typeStringInstall Touch Type
last_attributed_touch_data_custom_fieldsStringLast Attributed Touch Custom Fields
last_attributed_touch_data_dollar_3pStringAd Partner (3p)
last_attributed_touch_data_dollar_marketing_titleStringMarketing Title
last_attributed_touch_data_plus_current_featureStringCurrent Feature
last_attributed_touch_data_tilde_idLongLast Attributed Touch ID
last_attributed_touch_data_plus_touch_idStringLast Attributed Touch Touch ID
last_cta_view_data_plus_touch_idStringLast CTA View Touch ID
last_attributed_touch_data_plus_via_featuresArrayStringVia Features
last_attributed_touch_data_plus_web_formatStringWeb Format
last_attributed_touch_data_tilde_ad_idStringAd ID
last_attributed_touch_data_tilde_ad_nameStringAd Name
last_attributed_touch_data_tilde_ad_set_idStringAd Set ID
last_attributed_touch_data_tilde_ad_set_nameStringAd Set Name
last_attributed_touch_data_tilde_advertising_account_nameStringAdvertising Account Name
last_attributed_touch_data_tilde_advertising_account_idStringAdvertising Account ID
last_attributed_touch_data_tilde_advertising_partner_idStringAd Partner ID
last_attributed_touch_data_tilde_advertising_partner_nameStringAd Partner
last_attributed_touch_data_tilde_agencyStringAgency
last_attributed_touch_data_tilde_agency_idStringAgency ID
last_attributed_touch_data_tilde_banner_dimensionsStringBanner Dimensions
last_attributed_touch_data_tilde_branch_ad_formatStringBranch Ad Format
last_attributed_touch_data_tilde_campaignStringCampaign
last_attributed_touch_data_tilde_campaign_idStringCampaign ID
last_attributed_touch_data_tilde_campaign_typeStringCampaign Type
last_attributed_touch_data_tilde_channelStringChannel
last_attributed_touch_data_tilde_creative_nameStringCreative Name
last_attributed_touch_data_tilde_creative_idStringCreative ID
last_attributed_touch_data_tilde_customer_ad_nameStringCustomer Ad Name
last_attributed_touch_data_tilde_customer_ad_set_nameStringCustomer Ad Set Name
last_attributed_touch_data_tilde_customer_campaignStringCustomer Campaign
last_attributed_touch_data_tilde_customer_keywordStringCustomer Keyword
last_attributed_touch_data_tilde_customer_placementStringCustomer Placement
last_attributed_touch_data_tilde_customer_secondary_publisherStringCustomer Secondary Publisher
last_attributed_touch_data_tilde_customer_sub_site_nameStringCustomer Sub Site Name
last_attributed_touch_data_tilde_external_touch_idStringExternal Touch ID
last_attributed_touch_data_tilde_featureStringFeature
last_attributed_touch_data_tilde_journey_idStringJourney ID
last_attributed_touch_data_tilde_journey_nameStringJourney Name
last_attributed_touch_data_tilde_keywordStringKeyword
last_attributed_touch_data_tilde_keyword_idStringKeyword ID
last_attributed_touch_data_tilde_optimization_modelStringOptimization Model
last_attributed_touch_data_tilde_placementStringPlacement
last_attributed_touch_data_tilde_placement_idStringPlacement ID
last_attributed_touch_data_tilde_secondary_ad_formatStringSecondary Ad Format
last_attributed_touch_data_tilde_secondary_publisherStringSecondary Publisher
last_attributed_touch_data_tilde_secondary_publisher_idStringSecondary Publisher ID
last_attributed_touch_data_tilde_stageStringStage
last_attributed_touch_data_tilde_sub_site_nameStringSub Site Name
last_attributed_touch_data_tilde_tagsArrayStringTags
last_attributed_touch_data_tilde_technology_partnerStringTechnology Partner
last_attributed_touch_data_tilde_touch_subtypeStringGoogle Video Ads "Engaged View"
last_attributed_touch_data_tilde_view_idStringView ID
last_attributed_touch_data_tilde_view_nameStringView Name
last_attributed_touch_timestampLongLast Attributed Touch Timestamp
last_attributed_touch_timestamp_isoStringLast Attributed Touch Timestamp (ISO)
last_attributed_touch_typeStringLast Attributed Touch Type
last_cta_view_data_custom_fieldsStringLast CTA View Custom Fields
last_cta_view_data_dollar_3pStringLast CTA View Ad Partner (3p)
last_attributed_touch_data_plus_referring_domainStringReferring Domain
last_cta_view_data_plus_via_featuresArrayStringLast CTA View Via Features
last_cta_view_data_plus_web_formatStringLast CTA View Web Format
last_cta_view_data_tilde_ad_idStringLast CTA View Ad ID
last_cta_view_data_tilde_ad_nameStringLast CTA View Ad Name
last_cta_view_data_tilde_ad_set_idStringLast CTA View Ad Set ID
last_cta_view_data_tilde_ad_set_nameStringLast CTA View Ad Set Name
last_cta_view_data_tilde_advertising_partner_nameStringLast CTA View Ad Partner
last_cta_view_data_tilde_agencyStringLast CTA View Agency
last_cta_view_data_tilde_banner_dimensionsStringLast CTA View Banner Dimensions
last_cta_view_data_tilde_branch_ad_formatStringLast CTA View Branch Ad Format
last_cta_view_data_tilde_campaignStringLast CTA View Campaign
last_cta_view_data_tilde_campaign_idStringLast CTA View Campaign ID
last_cta_view_data_tilde_campaign_typeStringLast CTA View Campaign Type
last_cta_view_data_tilde_channelStringLast CTA View Channel
last_cta_view_data_tilde_creative_idStringLast CTA View Creative ID
last_cta_view_data_tilde_creative_nameStringLast CTA View Creative Name
last_cta_view_data_tilde_external_touch_idLongLast CTA View External Touch ID
last_cta_view_data_tilde_featureStringLast CTA View Feature
last_cta_view_data_tilde_idLongLast CTA View ID
last_cta_view_data_tilde_keyword_idStringLast CTA View Keyword ID
last_cta_view_data_tilde_optimization_modelStringLast CTA View Optimization Model
last_cta_view_data_tilde_placementStringLast CTA View Placement
last_cta_view_data_tilde_secondary_ad_formatStringLast CTA View Secondary Ad Format
last_cta_view_data_tilde_secondary_publisherStringLast CTA View Secondary Publisher<
last_cta_view_data_tilde_stageStringLast CTA View Stage
last_cta_view_data_tilde_tagsArrayStringLast CTA View Tags
last_cta_view_data_tilde_technology_partnerStringLast CTA View Technology Partner
last_cta_view_timestampLongLast CTA View Timestamp
last_cta_view_timestamp_isoStringLast CTA View Timestamp (ISO)
\+match_guaranteedbooleanFlag that determines if the app session was made with 100% accuracy. Only available in Custom Exports API
minutes_from_last_attributed_touch_to_eventIntegerMinutes From Last Attributed Touch To Event
nameStringName of event based on selected topic
organization_idLongOrganization ID
organization_nameStringOrganization Name
originStringOrigin
reengagement_activity_attributedBooleanReengagement Activity Attribute
reengagement_activity_data_has_clicked_adBooleanReengagement Has Clicked Ad
reengagement_activity_data_has_clicked_emailBooleanReengagement Has Clicked Email
reengagement_activity_timestampStringReengagement Timestamp
reengagement_activity_touch_data_additional_data_tilde_ad_idLongReengagement Ad ID
reengagement_activity_touch_data_additional_data_tilde_ad_set_idLongReengagement Ad Set ID
reengagement_activity_touch_data_additional_data_tilde_campaign_idLongReengagement Campaign ID
reengagement_activity_touch_data_additional_data_tilde_creative_idLongReengagement Creative ID
reengagement_activity_touch_data_dollar_3pStringReengagement Partner 3p Value
reengagement_activity_touch_data_plus_via_featuresStringReengagement Features
reengagement_activity_touch_data_plus_web_formatStringReengagement Web Format
reengagement_activity_touch_data_tilde_ad_nameStringReengagement Ad Name
reengagement_activity_touch_data_tilde_ad_set_nameStringReengagement Ad Set Name
reengagement_activity_touch_data_tilde_advertising_partner_idLongReengagement Advertising Partner ID
reengagement_activity_touch_data_tilde_advertising_partner_nameStringReengagement Advertising Partner Name
reengagement_activity_touch_data_tilde_agencyStringReengagement Agency
reengagement_activity_touch_data_tilde_agency_idLongReengagement Agency ID
reengagement_activity_touch_data_tilde_campaignStringReengagement Campaign
reengagement_activity_touch_data_tilde_channelStringReengagement Channel
reengagement_activity_touch_data_tilde_creative_nameStringReengagement Creative Name
reengagement_activity_touch_data_tilde_customer_ad_nameStringReengagement Customer Ad Name
reengagement_activity_touch_data_tilde_customer_ad_set_nameStringReengagement Customer Ad Set Name
reengagement_activity_touch_data_tilde_customer_campaignStringReengagement Customer Campaign
reengagement_activity_touch_data_tilde_customer_keywordStringReengagement Customer Keyword
reengagement_activity_touch_data_tilde_customer_placementStringReengagement Customer Placement
reengagement_activity_touch_data_tilde_customer_secondary_publisherStringReengagement Customer Secondary Publisher
reengagement_activity_touch_data_tilde_customer_sub_site_nameStringReengagement Customer Sub Site
reengagement_activity_touch_data_tilde_featureStringReengagement Feature
reengagement_activity_touch_data_tilde_journey_nameStringReengagement Journey Name
reengagement_activity_touch_data_tilde_keywordStringReengagement Keyword
reengagement_activity_touch_data_tilde_placementStringReengagement Placement
reengagement_activity_touch_data_tilde_secondary_publisherStringReengagement Secondary Publisher
reengagement_activity_touch_data_tilde_stageStringReengagement Stage
reengagement_activity_touch_data_tilde_tagsStringReengagement Tags
reengagement_activity_touch_data_tilde_view_nameStringReengagement View Name
reengagement_activity_touch_typeStringReengagement Touch Type
referrer_click_timestampLongReferrer Click Timestamp
seconds_from_install_to_eventIntegerSeconds From Install To Event
seconds_from_last_attributed_touch_to_eventIntegerSeconds From Last Attributed Touch To Event
seconds_from_last_attributed_touch_to_store_install_beginIntegerSeconds From Touch To Store Install Begin
site_event_items_countIntegerContent Items Count
store_install_begin_timestampLongStore Install Begin Timestamp
timestampLongTimestamp
timestamp_isoStringTimestamp (ISO)
user_data_aaidStringAAID
user_data_android_idStringAndroid ID
user_data_app_versionStringApp Version
user_data_brandStringBrand
user_data_browserStringBrowser
user_data_buildStringBuild
user_data_cpu_typeStringCPU Type
user_data_cross_platform_idStringCross Platform ID
user_data_developer_identityStringDeveloper Identity
user_data_device_typeStringDevice Type
user_data_environmentStringEnvironment
user_data_geo_city_codeIntegerCity Code
user_data_geo_city_enStringCity
user_data_geo_country_codeStringCountry Code
user_data_geo_country_enStringCountry
user_data_geo_dma_codeIntegerDMA Code
user_data_geo_latFloatLatitude
user_data_geo_lonFloatLongitude
user_data_geo_postal_codeStringPostal Code
user_data_geo_region_enStringRegion
user_data_geo_region_codeStringRegion Code
user_data_http_referrerStringHTTP Referrer
user_data_idfaStringIDFA
user_data_idfvStringIDFV
user_data_internet_connection_typeStringInternet Connection Type
user_data_ipStringIP Address
user_data_is_jailbrokenBooleanIIs Jailbroken
user_data_kindle_idStringKindle ID
user_data_languageStringLanguage
user_data_limit_ad_trackingBooleanLimit Ad Tracking
user_data_modelStringModel
user_data_oaidStringHuawei OAID
user_data_osStringOS
user_data_os_versionStringOS Version
user_data_os_version_androidStringOS Version (Android)
user_data_past_cross_platform_idsArrayStringPast Cross Platforms IDs
user_data_platformArrayStringPlatform
user_data_prob_cross_platform_idsArrayStructProbabilistic Cross Platform IDs
user_data_roku_ridaStringRoku Device ID
user_data_screen_heightIntegerScreen Height
user_data_screen_widthIntegerScreen Width
user_data_sdk_versionStringSDK Version
user_data_user_agentStringUser Agent
user_data_windows_aidStringWindows AID
user_data_device_localeStringDevice Locale
user_data_carrier_nameStringCarrier Name
user_data_opted_in_statusStringWhether user opted in to ATT or not
user_data_app_storeStringThe app store the user downloaded from

Available SKAdNetwork Message Fields

FieldTypeDescription
idvarcharSkAdNetwork Message ID
body_transaction_idvarcharSKAdNetwork Transaction ID
body_versionvarcharSKAdNetwork Version
body_ad_network_idvarcharSKAdNetwork Ad Network ID
body_campaign_idintegerSKAdNetworkCampaign ID
body_app_idbigintSKAdNetwork App ID (App Store ID)
body_attribution_signaturevarcharBody Attribution Signature
body_redownloadbooleanSKAdNetwork Redownload
body_source_app_idbigintSKAdNetwork Source App ID
body_conversion_valueintegerBody Conversion Value
body_fidelity_typeintegerBody Fidelity Type
body_did_winbooleanBody Did Win
body_coarse_conversion_valuevarcharCoarse Conversion Value (SkAdNetwork 4 and above)
body_source_domainvarcharSource Domain
body_source_identifierintegerApple Source Identifier (SkAdNetwork 4 and above)
body_postback_sequence_indexintegerPostback Window (SkAdNetwork 4 and above)
last_attributed_touch_data_tilde_creative_idvarcharAd Partner Creative Id
last_attributed_touch_data_tilde_creative_namevarcharAd Partner Creative Name
last_attributed_touch_data_tilde_ad_namevarcharAd Partner Ad Name
last_attributed_touch_data_tilde_ad_idvarcharAd Partner Ad Id
last_attributed_touch_data_tilde_ad_set_namevarcharAd Partner Ad Set Name
last_attributed_touch_data_tilde_ad_set_idvarcharAd Partner Ad Set ID
last_attributed_touch_data_tilde_campaign_idvarcharAd Partner Campaign ID
last_attributed_touch_data_tilde_campaignvarcharAd Partner Campaign Name
invalid_reasonvarcharInvalid Reason
timestampbigintTimestamp (when Branch received data)
event_timezone_adjusted_daybigintTimestamp (provided by Partner)
annotation_dollar_3pvarcharAnnotation Dollar 3P
annotation_conversion_value_mapped_valuevarcharAnnotation Conversion Vale Mapped Value
annotation_customer_event_aliasvarcharAnnotation Customer Event Alias
annotation_revenue_lowervarcharAnnotation Revenue Lower Bound
annotation_revenue_uppervarcharAnnotation Revenue Upper Bound
app_idbigintBranch App ID
organization_idbigintBranch Organization ID
advertiser_copyBooleanAdvertiser Copy for iOS 15+ devices

🚧

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 Topics

TopicHuman Readable Name
eo_click_blockedBlocked Clicks
eo_commerce_event_blockedBlocked Commerce Events
eo_content_event_blockedBlocked Content Events
eo_branch_cta_view_blockedBlocked CTA Views
eo_custom_event_blockedBlocked Custom Events
eo_impression_blockedBlocked Impressions
eo_install_blockedBlocked Installs
eo_open_blockedBlocked Opens
eo_pageview_blockedBlocked Pageviews
eo_reinstall_blockedBlocked Reinstalls
eo_sms_sent_blockedBlocked SMS Sent
eo_user_lifecycle_event_blockedBlocked User Lifecycle Events
eo_web_session_start_blockedBlocked Web Session Starts
eo_clickClicks
eo_commerce_eventCommerce Events
eo_content_eventContent Events
eo_branch_cta_viewCTA Views
eo_custom_eventCustom Events
eo_impressionImpressions
eo_installInstalls
eo_openOpens
eo_pageviewPageviews
webhook2Postback Records
eo_reinstallReinstalls
skadnetwork_invalid_messagesSKAdNetwork Invalid Messages
skadnetwork_valid_messagesSKAdNetwork Valid Messages
eo_sms_sentSMS Sent
eo_user_lifecycle_eventUser Lifecycle Events
eo_web_session_startWeb Session Starts
eo_san_touchSelf-Attributing Network Touch

🚧

Blocked Topics

Branch allows the export of blocked topics for up to 60 days from the time of the request.

Cthulhu Filter Specification

Cthulhu is a prefix notation syntax written in JSON for specifying filters on records (usually column-based records).

Purpose
Easily parses into an abstract syntax tree.

Glossary
any - any valid json basic value (number, string)
... - previous item in a list can repeat as many times as necessary

NameSpecExampleSQL Equivalent
eq["eq",<column:string>,
<value:any>]
["eq","x", 1]x= 1
gt["gt",<column:string>,
<value:any>]
["gt","x", 1]x> 1
gte["gte",<column:string>,
<value:any>]
["gte","x", 1]x >= 1
lt["lt",<column:string>,
<value:any>]
["lt","x", 1]x< 1
lte["lte",<column:string>,
<value:any>]
["lte","x", 1]x <= 1
like["like",<column:string>,
<value:regex>]
["like", "x", ". *foobar"]x LIKE "%
foobar"
between["between",<column:string>,
<lower:any>,
<upper:any>]
["between", "x",1, 2]x
BETWEEN
1 AND 2x >= 1 AND x <= 2
In["in", <column: string>, <value: any>, ...]["in","x", 1,2, 3]x IN (1,2,3)
and["and", , ...]["and",["gt","x", 1],["lt","x", 2]]x> 1 AND x < 2
or["or", , ...]["or",["eq","x", 1],["eq",
"x", 2]]
x = 1 OR x= 2
not["not",]["not",["eq","x", 1]]x != 1
array_contains["array_contains", , ]["array_contains","last_attributed_touch_data_tilde_tags","Share"]array_contains(array(1, 2, 3), 2)

Additional Examples

FilterMeaning
["eq","last_attributed_touch_data_dollar_3p","a_tiktok_ads"]Where last_attributed_touch_data_dollar_3p equals a_tiktok_ads.
["eq","name","PURCHASE"]Where name equals PURCHASE.
["or",["eq","name","store_page"],["eq","name","store_category_page"],["eq","name","dynamic_home_page"]]Where name equals store_page, store_category_pay, or dynamic_home_page.
["and",["eq","last_attributed_touch_data_dollar_3p","a_google_adwords"],["not",["eq","last_attributed_touch_data_tilde_external_touch_id",""]]]Where last_attributed_touch_data_dollar_3p equals a_google_adwords, and last_attributed_touch_data_tilde_external_touch_id is not empty.