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* |
|
Rate Limit for checking the status of a report* |
|
Exporting from test environments | At this moment, it is not possible to export data out of a Branch Test environment |
Repeated requests within 60 minutes will be cached | If 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:
- Created a Branch Dashboard
- Implemented the Branch SDK into your mobile app (iOS | Android)
- 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
- 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:
- In the left-hand navigation, under Configure, 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:
- Under Access Level, check the Export box.
- Under Permissions, check the Sensitive Data box.
- Optional: add data filters
- Under Data Filters, toggle any necessary data filters on/blue. Exported data will be filtered accordingly.
- Click Save.
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
Header | Description | Required |
---|---|---|
Access-Token | Key that encapsulates the user's permission w.r.t an org. Obtained from the Branch Dashboard needed for authentication. | Yes |
Content-Type | application/json | Yes |
Request Body Parameters
Parameter | Type | Description | Required |
---|---|---|---|
start_date | Date | The 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:00Z | Yes |
end_date | Date | The 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:999Z | Yes |
report_type | String | The Branch EO topic to be exported. | Yes |
fields | Comma Separated List | List of comma-separated fields desired in results. | Yes |
limit | Integer | If 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 |
timezone | String | Timezone 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 |
filter | Comma Separated List | Filter 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_format | String | Format 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_files | Boolean | Set 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_compression | String | The file compression method to use for the data. Options: - gz - snappy | Yes if you set allow_multiple_files to true |
Response Body Parameters
Parameter | Description |
---|---|
handle | Unique request handle generated against the endpoint call. |
export_job_status_url | The 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 Code | Description |
---|---|
200 | Status of aggregate export. |
400 | Authentication Failed. |
Get Export Request
GET /v2/logs/JOB_ID
Headers:
Access-Token: API_KEY
Host: api2.branch.io
Request Headers
Header | Description | Required |
---|---|---|
Access-Token | Key that encapsulates the user's permission w.r.t an org. Obtained from the Branch Dashboard needed for authentication. | Yes |
Content-Type | application/json | Yes |
Response Path Parameters
Parameter | Type | Description | Required |
---|---|---|---|
request_handle | String | The ID returned by the log export queue. | Yes |
Request Query Parameters
Parameter | Type | Description | Required |
---|---|---|---|
limit | Integer | The maximum number of results to return. | No |
format | String | Format of returned data. json or csv | No |
Response Body Parameters
Parameter | Type | Description |
---|---|---|
code | Integer | The response code. |
lines_exported | Integer | Number of lines exported against the originated request. |
status | String | Request status over the current execution time. |
status_url | String | The 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 Code | Description |
---|---|
200 | Status of aggregate export |
400 | Authentication Failed |
404 | Job ID Not Found |
Status Values
Status | Description |
---|---|
pending | Request is pending. |
running | Request is still running. |
complete | Request is complete. |
fail | Request 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
Header | Description | Required |
---|---|---|
Access-Token | Key that encapsulates the user's permissions with regard to an org. Obtained from the Branch Dashboard and needed for authentication. | Yes |
Content-Type | application/json | Yes |
Request Body Parameters
Parameter | Type | Description | Required |
---|---|---|---|
date | String | The start of the interval time range, in the format YYYY-MM-DD hh:mm:ss (must be within the past year). | Yes |
warehouse_meta_type | String | The type of data to check for. Can be either EVENT or AGGREGATE . | Yes |
topic | String | The Branch EO topic to be exported. | Yes |
app_id | Integer | Your Branch App ID, found under Account Settings in your Branch Dashboard. | Yes |
Response Body Parameters
Parameter | Description |
---|---|
data_ready | Whether or not the requested data is ready; can be true or false . |
date | The 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 Code | Description |
---|---|
200 | Status of data successfully retrieved. |
400 | Topic is invalid or data retention for requested data has expired. |
500 | Internal server error (Branch failure). |
Appendix
Available EO Fields
Fields | Type | Description |
---|---|---|
app_id | Long | App ID (capitalize ID in Liveview) |
app_name | String | App Name |
attributed | Boolean | Attributed |
content_items | ArrayStruct | Content Items |
custom_data | MapStringString | Custom Data |
customer_event_alias | String | Customer Event Alias |
days_from_last_attributed_touch_to_event | Integer | Days From Last Attributed Touch To Event |
deep_linked | Boolean | Deep Linked |
di_match_click_token | Long | DI Match Click Token |
event_data_ad_type | enum { BANNER, INTERSTITIAL, REWARDED_VIDEO, NATIVE } | Ad Type |
event_data_affiliation | String | Affiliation |
event_data_coupon | String | Coupon |
event_data_currency | String | Currency |
event_data_description | String | Event Description |
event_data_exchange_rate | Double | Exchange Rate |
event_data_revenue | Double | Revenue |
event_data_revenue_in_usd | Double | Revenue In USD |
event_data_search_query | String | Search Query |
event_data_shipping | Double | Shipping |
event_data_tax | Double | Tax |
event_data_transaction_id | String | Transaction ID |
event_data_local_currency | String | Local Currency |
event_data_local_currency_exchange_rate | String | Local Currency Exchange Rate |
event_data_revenue_in_local_currency | String | Revenue in Local Currency |
event_data_custom_param_1 | String | Custom parameter for event |
event_data_custom_param_2 | String | Custom parameter for event |
event_data_custom_param_3 | String | Custom parameter for event |
event_timestamp | Long | Event Timestamp |
existing_user | Boolean | Existing User |
external_intent_uri | String | External Intent URI |
first_event_for_user | Boolean | First Event For User |
hash_version | String | Hash Version |
hours_from_last_attributed_touch_to_event | Integer | House From Last Attributed Touch To Event |
id | String | ID |
install_activity_attributed | Boolean | Install Attributed |
install_activity_data_has_clicked_ad | Boolean | Install Has Clicked Ad |
install_activity_data_has_clicked_email | Boolean | Install Has Clicked Email |
install_activity_timestamp | Long | Install Timestamp |
install_activity_touch_data_additional_data_tilde_ad_id | Long | Install Ad ID |
install_activity_touch_data_additional_data_tilde_ad_set_id | Long | Install Ad Set ID |
install_activity_touch_data_additional_data_tilde_campaign_id | Long | Install Campaign ID |
install_activity_touch_data_additional_data_tilde_creative_id | Long | Install Creative ID |
install_activity_touch_data_dollar_3p | String | Install Partner 3p Value |
install_activity_touch_data_plus_via_features | String | Install Features |
install_activity_touch_data_plus_web_format | String | Install Web Format |
install_activity_touch_data_tilde_ad_name | String | Install Ad Name |
install_activity_touch_data_tilde_ad_set_name | String | Install Ad Set Name |
install_activity_touch_data_tilde_advertising_partner_id | Long | Install Ad Partner ID |
install_activity_touch_data_tilde_advertising_partner_name | String | Install Ad Partner |
install_activity_touch_data_tilde_agency | String | Install Agency |
install_activity_touch_data_tilde_agency_id | Long | Install Agency ID |
install_activity_touch_data_tilde_campaign | String | Install Campaign |
install_activity_touch_data_tilde_channel | String | Install Channel |
install_activity_touch_data_tilde_creative_name | String | Install Creative Name |
install_activity_touch_data_tilde_customer_ad_name | String | Install Customer Ad Name |
install_activity_touch_data_tilde_customer_ad_set_name | String | Install Customer Ad Set Name |
install_activity_touch_data_tilde_customer_campaign | String | Install Customer Campaign |
install_activity_touch_data_tilde_customer_keyword | String | Install Customer Keyword |
install_activity_touch_data_tilde_customer_placement | String | Install Customer Placement |
install_activity_touch_data_tilde_customer_secondary_publisher | String | Install Customer Secondary Publisher |
install_activity_touch_data_tilde_customer_sub_site_name | String | Install Customer Sub Site Name |
install_activity_touch_data_tilde_feature | String | Install Feature |
install_activity_touch_data_tilde_journey_name | String | Install Journey Name |
install_activity_touch_data_tilde_keyword | String | Install Keyword |
install_activity_touch_data_tilde_placement | String | Install Placement |
install_activity_touch_data_tilde_secondary_publisher | String | Install Secondary Publisher |
install_activity_touch_data_tilde_stage | String | Install Stage |
install_activity_touch_data_tilde_tags | String | Install Tags |
install_activity_touch_data_tilde_view_name | String | Install View Name` |
install_activity_touch_type | String | Install Touch Type |
last_attributed_touch_data_custom_fields | String | Last Attributed Touch Custom Fields |
last_attributed_touch_data_dollar_3p | String | Ad Partner (3p) |
last_attributed_touch_data_dollar_marketing_title | String | Marketing Title |
last_attributed_touch_data_plus_current_feature | String | Current Feature |
last_attributed_touch_data_tilde_id | Long | Last Attributed Touch ID |
last_attributed_touch_data_plus_touch_id | String | Last Attributed Touch Touch ID |
last_cta_view_data_plus_touch_id | String | Last CTA View Touch ID |
last_attributed_touch_data_plus_via_features | ArrayString | Via Features |
last_attributed_touch_data_plus_web_format | String | Web Format |
last_attributed_touch_data_tilde_ad_id | String | Ad ID |
last_attributed_touch_data_tilde_ad_name | String | Ad Name |
last_attributed_touch_data_tilde_ad_set_id | String | Ad Set ID |
last_attributed_touch_data_tilde_ad_set_name | String | Ad Set Name |
last_attributed_touch_data_tilde_advertising_account_name | String | Advertising Account Name |
last_attributed_touch_data_tilde_advertising_account_id | String | Advertising Account ID |
last_attributed_touch_data_tilde_advertising_partner_id | String | Ad Partner ID |
last_attributed_touch_data_tilde_advertising_partner_name | String | Ad Partner |
last_attributed_touch_data_tilde_agency | String | Agency |
last_attributed_touch_data_tilde_agency_id | String | Agency ID |
last_attributed_touch_data_tilde_banner_dimensions | String | Banner Dimensions |
last_attributed_touch_data_tilde_branch_ad_format | String | Branch Ad Format |
last_attributed_touch_data_tilde_campaign | String | Campaign |
last_attributed_touch_data_tilde_campaign_id | String | Campaign ID |
last_attributed_touch_data_tilde_campaign_type | String | Campaign Type |
last_attributed_touch_data_tilde_channel | String | Channel |
last_attributed_touch_data_tilde_creative_name | String | Creative Name |
last_attributed_touch_data_tilde_creative_id | String | Creative ID |
last_attributed_touch_data_tilde_customer_ad_name | String | Customer Ad Name |
last_attributed_touch_data_tilde_customer_ad_set_name | String | Customer Ad Set Name |
last_attributed_touch_data_tilde_customer_campaign | String | Customer Campaign |
last_attributed_touch_data_tilde_customer_keyword | String | Customer Keyword |
last_attributed_touch_data_tilde_customer_placement | String | Customer Placement |
last_attributed_touch_data_tilde_customer_secondary_publisher | String | Customer Secondary Publisher |
last_attributed_touch_data_tilde_customer_sub_site_name | String | Customer Sub Site Name |
last_attributed_touch_data_tilde_external_touch_id | String | External Touch ID |
last_attributed_touch_data_tilde_feature | String | Feature |
last_attributed_touch_data_tilde_journey_id | String | Journey ID |
last_attributed_touch_data_tilde_journey_name | String | Journey Name |
last_attributed_touch_data_tilde_keyword | String | Keyword |
last_attributed_touch_data_tilde_keyword_id | String | Keyword ID |
last_attributed_touch_data_tilde_optimization_model | String | Optimization Model |
last_attributed_touch_data_tilde_placement | String | Placement |
last_attributed_touch_data_tilde_placement_id | String | Placement ID |
last_attributed_touch_data_tilde_secondary_ad_format | String | Secondary Ad Format |
last_attributed_touch_data_tilde_secondary_publisher | String | Secondary Publisher |
last_attributed_touch_data_tilde_secondary_publisher_id | String | Secondary Publisher ID |
last_attributed_touch_data_tilde_stage | String | Stage |
last_attributed_touch_data_tilde_sub_site_name | String | Sub Site Name |
last_attributed_touch_data_tilde_tags | ArrayString | Tags |
last_attributed_touch_data_tilde_technology_partner | String | Technology Partner |
last_attributed_touch_data_tilde_touch_subtype | String | Google Video Ads "Engaged View" |
last_attributed_touch_data_tilde_view_id | String | View ID |
last_attributed_touch_data_tilde_view_name | String | View Name |
last_attributed_touch_timestamp | Long | Last Attributed Touch Timestamp |
last_attributed_touch_timestamp_iso | String | Last Attributed Touch Timestamp (ISO) |
last_attributed_touch_type | String | Last Attributed Touch Type |
last_cta_view_data_custom_fields | String | Last CTA View Custom Fields |
last_cta_view_data_dollar_3p | String | Last CTA View Ad Partner (3p) |
last_attributed_touch_data_plus_referring_domain | String | Referring Domain |
last_cta_view_data_plus_via_features | ArrayString | Last CTA View Via Features |
last_cta_view_data_plus_web_format | String | Last CTA View Web Format |
last_cta_view_data_tilde_ad_id | String | Last CTA View Ad ID |
last_cta_view_data_tilde_ad_name | String | Last CTA View Ad Name |
last_cta_view_data_tilde_ad_set_id | String | Last CTA View Ad Set ID |
last_cta_view_data_tilde_ad_set_name | String | Last CTA View Ad Set Name |
last_cta_view_data_tilde_advertising_partner_name | String | Last CTA View Ad Partner |
last_cta_view_data_tilde_agency | String | Last CTA View Agency |
last_cta_view_data_tilde_banner_dimensions | String | Last CTA View Banner Dimensions |
last_cta_view_data_tilde_branch_ad_format | String | Last CTA View Branch Ad Format |
last_cta_view_data_tilde_campaign | String | Last CTA View Campaign |
last_cta_view_data_tilde_campaign_id | String | Last CTA View Campaign ID |
last_cta_view_data_tilde_campaign_type | String | Last CTA View Campaign Type |
last_cta_view_data_tilde_channel | String | Last CTA View Channel |
last_cta_view_data_tilde_creative_id | String | Last CTA View Creative ID |
last_cta_view_data_tilde_creative_name | String | Last CTA View Creative Name |
last_cta_view_data_tilde_external_touch_id | Long | Last CTA View External Touch ID |
last_cta_view_data_tilde_feature | String | Last CTA View Feature |
last_cta_view_data_tilde_id | Long | Last CTA View ID |
last_cta_view_data_tilde_keyword_id | String | Last CTA View Keyword ID |
last_cta_view_data_tilde_optimization_model | String | Last CTA View Optimization Model |
last_cta_view_data_tilde_placement | String | Last CTA View Placement |
last_cta_view_data_tilde_secondary_ad_format | String | Last CTA View Secondary Ad Format |
last_cta_view_data_tilde_secondary_publisher | String | Last CTA View Secondary Publisher< |
last_cta_view_data_tilde_stage | String | Last CTA View Stage |
last_cta_view_data_tilde_tags | ArrayString | Last CTA View Tags |
last_cta_view_data_tilde_technology_partner | String | Last CTA View Technology Partner |
last_cta_view_timestamp | Long | Last CTA View Timestamp |
last_cta_view_timestamp_iso | String | Last CTA View Timestamp (ISO) |
\+match_guaranteed | boolean | Flag that determines if the app session was made with 100% accuracy. Only available in Custom Exports API |
minutes_from_last_attributed_touch_to_event | Integer | Minutes From Last Attributed Touch To Event |
name | String | Name of event based on selected topic |
organization_id | Long | Organization ID |
organization_name | String | Organization Name |
origin | String | Origin |
reengagement_activity_attributed | Boolean | Reengagement Activity Attribute |
reengagement_activity_data_has_clicked_ad | Boolean | Reengagement Has Clicked Ad |
reengagement_activity_data_has_clicked_email | Boolean | Reengagement Has Clicked Email |
reengagement_activity_timestamp | String | Reengagement Timestamp |
reengagement_activity_touch_data_additional_data_tilde_ad_id | Long | Reengagement Ad ID |
reengagement_activity_touch_data_additional_data_tilde_ad_set_id | Long | Reengagement Ad Set ID |
reengagement_activity_touch_data_additional_data_tilde_campaign_id | Long | Reengagement Campaign ID |
reengagement_activity_touch_data_additional_data_tilde_creative_id | Long | Reengagement Creative ID |
reengagement_activity_touch_data_dollar_3p | String | Reengagement Partner 3p Value |
reengagement_activity_touch_data_plus_via_features | String | Reengagement Features |
reengagement_activity_touch_data_plus_web_format | String | Reengagement Web Format |
reengagement_activity_touch_data_tilde_ad_name | String | Reengagement Ad Name |
reengagement_activity_touch_data_tilde_ad_set_name | String | Reengagement Ad Set Name |
reengagement_activity_touch_data_tilde_advertising_partner_id | Long | Reengagement Advertising Partner ID |
reengagement_activity_touch_data_tilde_advertising_partner_name | String | Reengagement Advertising Partner Name |
reengagement_activity_touch_data_tilde_agency | String | Reengagement Agency |
reengagement_activity_touch_data_tilde_agency_id | Long | Reengagement Agency ID |
reengagement_activity_touch_data_tilde_campaign | String | Reengagement Campaign |
reengagement_activity_touch_data_tilde_channel | String | Reengagement Channel |
reengagement_activity_touch_data_tilde_creative_name | String | Reengagement Creative Name |
reengagement_activity_touch_data_tilde_customer_ad_name | String | Reengagement Customer Ad Name |
reengagement_activity_touch_data_tilde_customer_ad_set_name | String | Reengagement Customer Ad Set Name |
reengagement_activity_touch_data_tilde_customer_campaign | String | Reengagement Customer Campaign |
reengagement_activity_touch_data_tilde_customer_keyword | String | Reengagement Customer Keyword |
reengagement_activity_touch_data_tilde_customer_placement | String | Reengagement Customer Placement |
reengagement_activity_touch_data_tilde_customer_secondary_publisher | String | Reengagement Customer Secondary Publisher |
reengagement_activity_touch_data_tilde_customer_sub_site_name | String | Reengagement Customer Sub Site |
reengagement_activity_touch_data_tilde_feature | String | Reengagement Feature |
reengagement_activity_touch_data_tilde_journey_name | String | Reengagement Journey Name |
reengagement_activity_touch_data_tilde_keyword | String | Reengagement Keyword |
reengagement_activity_touch_data_tilde_placement | String | Reengagement Placement |
reengagement_activity_touch_data_tilde_secondary_publisher | String | Reengagement Secondary Publisher |
reengagement_activity_touch_data_tilde_stage | String | Reengagement Stage |
reengagement_activity_touch_data_tilde_tags | String | Reengagement Tags |
reengagement_activity_touch_data_tilde_view_name | String | Reengagement View Name |
reengagement_activity_touch_type | String | Reengagement Touch Type |
referrer_click_timestamp | Long | Referrer Click Timestamp |
seconds_from_install_to_event | Integer | Seconds From Install To Event |
seconds_from_last_attributed_touch_to_event | Integer | Seconds From Last Attributed Touch To Event |
seconds_from_last_attributed_touch_to_store_install_begin | Integer | Seconds From Touch To Store Install Begin |
site_event_items_count | Integer | Content Items Count |
store_install_begin_timestamp | Long | Store Install Begin Timestamp |
timestamp | Long | Timestamp |
timestamp_iso | String | Timestamp (ISO) |
user_data_aaid | String | AAID |
user_data_android_id | String | Android ID |
user_data_app_version | String | App Version |
user_data_brand | String | Brand |
user_data_browser | String | Browser |
user_data_build | String | Build |
user_data_cpu_type | String | CPU Type |
user_data_cross_platform_id | String | Cross Platform ID |
user_data_developer_identity | String | Developer Identity |
user_data_device_type | String | Device Type |
user_data_environment | String | Environment |
user_data_geo_city_code | Integer | City Code |
user_data_geo_city_en | String | City |
user_data_geo_country_code | String | Country Code |
user_data_geo_country_en | String | Country |
user_data_geo_dma_code | Integer | DMA Code |
user_data_geo_lat | Float | Latitude |
user_data_geo_lon | Float | Longitude |
user_data_geo_postal_code | String | Postal Code |
user_data_geo_region_en | String | Region |
user_data_geo_region_code | String | Region Code |
user_data_http_referrer | String | HTTP Referrer |
user_data_idfa | String | IDFA |
user_data_idfv | String | IDFV |
user_data_internet_connection_type | String | Internet Connection Type |
user_data_ip | String | IP Address |
user_data_is_jailbroken | Boolean | IIs Jailbroken |
user_data_kindle_id | String | Kindle ID |
user_data_language | String | Language |
user_data_limit_ad_tracking | Boolean | Limit Ad Tracking |
user_data_model | String | Model |
user_data_oaid | String | Huawei OAID |
user_data_os | String | OS |
user_data_os_version | String | OS Version |
user_data_os_version_android | String | OS Version (Android) |
user_data_past_cross_platform_ids | ArrayString | Past Cross Platforms IDs |
user_data_platform | ArrayString | Platform |
user_data_prob_cross_platform_ids | ArrayStruct | Probabilistic Cross Platform IDs |
user_data_roku_rida | String | Roku Device ID |
user_data_screen_height | Integer | Screen Height |
user_data_screen_width | Integer | Screen Width |
user_data_sdk_version | String | SDK Version |
user_data_user_agent | String | User Agent |
user_data_windows_aid | String | Windows AID |
user_data_device_locale | String | Device Locale |
user_data_carrier_name | String | Carrier Name |
user_data_opted_in_status | String | Whether user opted in to ATT or not |
user_data_app_store | String | The app store the user downloaded from |
Available SKAdNetwork Message Fields
Field | Type | Description |
---|---|---|
id | varchar | SkAdNetwork Message ID |
body_transaction_id | varchar | SKAdNetwork Transaction ID |
body_version | varchar | SKAdNetwork Version |
body_ad_network_id | varchar | SKAdNetwork Ad Network ID |
body_campaign_id | integer | SKAdNetworkCampaign ID |
body_app_id | bigint | SKAdNetwork App ID (App Store ID) |
body_attribution_signature | varchar | Body Attribution Signature |
body_redownload | boolean | SKAdNetwork Redownload |
body_source_app_id | bigint | SKAdNetwork Source App ID |
body_conversion_value | integer | Body Conversion Value |
body_fidelity_type | integer | Body Fidelity Type |
body_did_win | boolean | Body Did Win |
body_coarse_conversion_value | varchar | Coarse Conversion Value (SkAdNetwork 4 and above) |
body_source_domain | varchar | Source Domain |
body_source_identifier | integer | Apple Source Identifier (SkAdNetwork 4 and above) |
body_postback_sequence_index | integer | Postback Window (SkAdNetwork 4 and above) |
last_attributed_touch_data_tilde_creative_id | varchar | Ad Partner Creative Id |
last_attributed_touch_data_tilde_creative_name | varchar | Ad Partner Creative Name |
last_attributed_touch_data_tilde_ad_name | varchar | Ad Partner Ad Name |
last_attributed_touch_data_tilde_ad_id | varchar | Ad Partner Ad Id |
last_attributed_touch_data_tilde_ad_set_name | varchar | Ad Partner Ad Set Name |
last_attributed_touch_data_tilde_ad_set_id | varchar | Ad Partner Ad Set ID |
last_attributed_touch_data_tilde_campaign_id | varchar | Ad Partner Campaign ID |
last_attributed_touch_data_tilde_campaign | varchar | Ad Partner Campaign Name |
invalid_reason | varchar | Invalid Reason |
timestamp | bigint | Timestamp (when Branch received data) |
event_timezone_adjusted_day | bigint | Timestamp (provided by Partner) |
annotation_dollar_3p | varchar | Annotation Dollar 3P |
annotation_conversion_value_mapped_value | varchar | Annotation Conversion Vale Mapped Value |
annotation_customer_event_alias | varchar | Annotation Customer Event Alias |
annotation_revenue_lower | varchar | Annotation Revenue Lower Bound |
annotation_revenue_upper | varchar | Annotation Revenue Upper Bound |
app_id | bigint | Branch App ID |
organization_id | bigint | Branch Organization ID |
advertiser_copy | Boolean | Advertiser 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
Topic | Human Readable Name |
---|---|
eo_click_blocked | Blocked Clicks |
eo_commerce_event_blocked | Blocked Commerce Events |
eo_content_event_blocked | Blocked Content Events |
eo_branch_cta_view_blocked | Blocked CTA Views |
eo_custom_event_blocked | Blocked Custom Events |
eo_impression_blocked | Blocked Impressions |
eo_install_blocked | Blocked Installs |
eo_open_blocked | Blocked Opens |
eo_pageview_blocked | Blocked Pageviews |
eo_reinstall_blocked | Blocked Reinstalls |
eo_sms_sent_blocked | Blocked SMS Sent |
eo_user_lifecycle_event_blocked | Blocked User Lifecycle Events |
eo_web_session_start_blocked | Blocked Web Session Starts |
eo_click | Clicks |
eo_commerce_event | Commerce Events |
eo_content_event | Content Events |
eo_branch_cta_view | CTA Views |
eo_custom_event | Custom Events |
eo_impression | Impressions |
eo_install | Installs |
eo_open | Opens |
eo_pageview | Pageviews |
webhook2 | Postback Records |
eo_reinstall | Reinstalls |
skadnetwork_invalid_messages | SKAdNetwork Invalid Messages |
skadnetwork_valid_messages | SKAdNetwork Valid Messages |
eo_sms_sent | SMS Sent |
eo_user_lifecycle_event | User Lifecycle Events |
eo_web_session_start | Web Session Starts |
eo_san_touch | Self-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
Name | Spec | Example | SQL 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
Filter | Meaning |
---|---|
["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. |