Post Query

  • Published on Feb 25, 2025
Post
/query/analytics

This endpoint provides a way to query dashboard analytics without having to access the Branch Dashboard.

Query parameters
limit
integer

Maximum number of results to return in the response. If granularity is set to day, Branch will pull results up to the limit for each day. So if limit is set to 1000 and 5 days worth of data is queried, with granularity=day, then this API will return up to 5000 results.

Maximum1000
Example100
after
integer

A pagination parameter indicating the index of the first result to return in the response. Eg, with 100 results returned, setting "after" to 50 would return elements 51-100

query_id
string

Returned as query parameter on the "paging" object nexturl and previous_url. Locks the last event to count for a query, so new events that occur between queries are not added to the results (prevents count change over time)

Body parameters
Expand All
object

Query Request Body

branch_key
string Required

The Branch key of the app analytics information is being pulled for.

Examplekey_live_xxxx
branch_secret
string Required

The Branch secret of the app, used for authentication.

Examplesecret_live_xxxx
start_date
string (date) Required

A timestamp representing the oldest date to return data for. Timezone of the timestamp is set in your Branch Dashboard configuration. Please note that start_date cannot be earlier than 2017-10-14.

Example2023-05-01
end_date
string (date) Required

The last timestamp (exclusive) to return data for. No events that triggered after the enddate will be counted in the query results. Timezone of the timestamp is set in your Branch Dashboard configuration. Please note that end_date cannot be more than 7 days after the startdate

Example2023-05-07
data_source
string Required

The type of event to query for. The values are valid Branch data sources. Here are the descriptions:

  • eo_impression - Real-time User-device level impressions/ad-views triggered via Impression Tracking Ad Links. SAN Ad Partner's impressions not included in this data source.
  • eo_click - Real-time user-device level Link clicks recorded through User Clicks on the Branch Links. SAN Ad Partner's clicks are not included in this bucket.
  • xx_impression - Combined Aggregated Data Source containing both Real-Time user-device level impressions and the SAN Ad Partner's Impressions passed to Branch Systems from SAN servers.
  • xx_click - Combined Aggregated Data source containing both Reat-Time User-device level Clicks and the SAN Ad Partner's Clicks passed to Branch systems from SAN servers.
Valid values[ "eo_impression", "eo_click", "xx_impression", "xx_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" ]
Default"eo_install"
Exampleeo_install
aggregation
string Required

How to count events towards the final result count. When using unique_count, each event is only counted if an event by that user has not already been seen.

Valid values[ "unique_count", "total_count", "revenue", "cost", "cost_in_local_currency" ]
Default"total_count"
Exampletotal_count
dimensions
Array of string Required

List of event fields to use as splits for the query. Results counts are returned grouped with other events that have matchings values for each key provided in dimensions.

string
Valid values[ "name", "origin", "timestamp", "deep_linked", "from_desktop", "attributed", "last_attributed_touch_type", "last_attributed_touch_data_tilde_tags", "last_attributed_touch_data_tilde_secondary_publisher", "last_attributed_touch_data_plus_current_feature", "last_attributed_touch_data_plus_via_features", "last_attributed_touch_data_tilde_campaign", "last_attributed_touch_data_tilde_advertising_partner_name", "last_attributed_touch_data_tilde_feature", "last_attributed_touch_data_tilde_creative_name", "last_attributed_touch_data_plus_web_format", "last_attributed_touch_data_tilde_creative_id", "last_attributed_touch_data_tilde_ad_name", "last_attributed_touch_data_tilde_ad_id", "last_attributed_touch_data_tilde_campaign_id", "last_attributed_touch_data_tilde_placement", "last_attributed_touch_data_tilde_stage", "last_attributed_touch_data_tilde_channel", "last_attributed_touch_data_tilde_ad_set_name", "last_attributed_touch_data_tilde_ad_set_id", "last_attributed_touch_data_tilde_keyword", "last_attributed_touch_data_tilde_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_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_tilde_marketing_title", "last_attributed_touch_data_dollar_marketing_title", "last_attributed_touch_data_dollar_3p", "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_geo_region_en", "user_data_opted_in", "user_data_opted_in_status", "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", "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" ]
Default"attributed"
Exampleattributed
filters
object (filterBodyDictionary)
Example{ "!last_attributed_touch_data_plus_current_feature": [ "MOBILE_DEEPVIEWS", "DESKTOP_DEEPVIEWS" ] }
property*
Array of string additionalProperties
string
enable_install_recalculation
boolean

This field related to Result formatting. De-dupe unattributed installs caused by duplicate events from non-opt-in users coming from paid ads.

Defaultfalse
ExampleFalse
granularity
string

This field related to Result formatting. Range of time to roll multiple events into a single result count. Eg, with a value of "day" the counts for each day are returned independently, where "all" would return a single count for the entire time range.

Valid values[ "all", "day" ]
Default"all"
Exampleall
ordered_by
string

Field indicates which key of result to sort results on. Only supports 1 sort key as of now. Possible values are any element of query "dimensions" or the value of "aggregation" in the query

Valid values[ "name", "origin", "timestamp", "deep_linked", "from_desktop", "attributed", "unique_count", "total_count", "revenue", "cost", "cost_in_local_currency" ]
Default"attributed"
Exampleattributed
ordered
string

Field indicates the sorting order of the output.

Valid values[ "ascending", "descending" ]
Default"descending"
Exampledescending
zero_fill
boolean

Whether to return result objects where the result count was 0. If set to false, results with count = 0 will be omitted from the response. If result is empty and zerofill=true, fields will be loaded with null/0 to provide a schema.

Defaultfalse
ExampleFalse
Responses
200

Status of aggregate export

Result
"\"{\n        \"results\": [\n            {\n                \"result\": {\n                    \"attributed\": \"true\",\n                    \"total_count\": 129\n                },\n                \"timestamp\": \"2023-05-01T00:00:00.000-08:00\"\n            },\n            {\n                \"result\": {\n                    \"attributed\": \"true\",\n                    \"total_count\": 125\n                },\n                \"timestamp\": \"2023-05-04T00:00:00.000-08:00\"\n            },\n            {\n                \"result\": {\n                    \"attributed\": \"true\",\n                    \"total_count\": 120\n                },\n                \"timestamp\": \"2023-05-02T00:00:00.000-08:00\"\n            },\n            {\n                \"result\": {\n                    \"attributed\": \"false\",\n                    \"total_count\": 95\n                },\n                \"timestamp\": \"2023-05-04T00:00:00.000-08:00\"\n            },\n            {\n                \"result\": {\n                    \"attributed\": \"false\",\n                    \"total_count\": 79\n                },\n                \"timestamp\": \"2023-05-06T00:00:00.000-08:00\"\n            }\n        ],\n        \"paging\": {\n            \"next_url\": \"/v1/query/analytics?limit=5&after=5\",\n            \"total_count\": 14\n        }\n    }\"      \n"
Expand All
object
results
object
result
object (QuerResultObject)
attributed
boolean
ExampleTrue
total_count
integer
Example129
timestamp
string (data-time)

N/A

Example2023-05-01T00:00:00.000-08:00
paging
object
next_url
string

URL to next result set

Example/v1/query/analytics?limit=5&after=5
total_count
integer

Number of total records retrieved against search

Example14
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