Overview

The Query API lets you use your own unique queries to fetch the particular pre-aggregated analytics data that you're interested in.

Benefits

The Branch Query API gives you access to the same pre-aggregated analytics data that is displayed in your Branch Dashboard, without needing to access the Dashboard itself.

An individual query is constructed from three types of parameters:

Authentication parameters that control the access to the data.
Data selection keys that define which events are eligible to be counted in the results (e.g. filters).
Result format specifiers that define which results are included in the HTTP response and how the results are returned (e.g. sorting).

Limits

Limitation	Details
Rate Limits	- 5 requests per second - 20 requests per minute - 150 requests per hour If you've hit the rate limit, you'll see an error message which says `Limit is exceeded for org....` in the response body.
Max number of rows returned from API	50,000
Max retrievable unique values for a single dimension (e.g. campaigns, ad names, etc.)	40,000
Max number of days that can be queried at a time	7 days If more records are required, please make multiple requests with smaller time intervals to pull the necessary data in batches.
Export Window	Rolling 2 year window.
Specific Dimension Combinations	If you are pulling from SAN `cost`, `xx_click`, or `xx_impression` data, you cannot use the following dimension combinations: 1. `user_data_os` together with `user_data_geo_country_code` 2. `last_attributed_touch_data_tilde_secondary_publisher` together with `user_data_geo_country_code`

Try It!

Try out the Query API in your browser, using your Branch data:

Post Query

We also strongly suggest checking out our Query Recipe Book for use cases and examples related to this API. It has screenshots of Branch Dashboard visualizations alongside the queries you would need to make to pull the same data from the API. Try it for a quick way to get up and running with this API!

Getting Started

Prerequisites

In order to use the Query API, you first need to:

Create a Branch Dashboard.
Enable Universal Ads and start running ad campaigns from your Branch account.
Implement the appropriate Branch SDK into your mobile app (iOS | Android).
Make sure you have the appropriate permissions set on your user account. See the Access section for more.

Access

General Access

To access the Query API, a user must have both Aggregate Data and Export access enabled on their account.

Agency Access

If you work with an agency that runs your advertising campaigns and want to give them access to export the subsequent data, you can provide them with access to the Export API.

To provide an agency team member with access to the Export API:

In the left-hand navigation, under Setup & Testing, 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:
1. Under Access Level, check the Export box.
2. Under Permissions, check the Aggregate Data box.
Add data filters (optional):
1. 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 aggregate data associated with all of your campaigns, regardless if they are associated with them or not.

Authentication

Calls to the Query API require your Branch Key and Branch Secret. Both your Branch Key and your Branch Secret can be obtained through your Branch Dashboard Account Settings.

Usage

Post Query

Request Info

Export Request

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

Request Headers

Header	Description	Required
`accept`	application/json	Yes
`content-type`	application/json	Yes

Request Query Parameters

Parameter	Type	Description	Required
`branch_key`	String	The Branch Key for the relevant application.	Yes
`branch_secret`	String	The Branch Secret for the relevant application, used for authentication.	Yes
`limit`	Integer	The maximum number of results to return in the response. Default value: `100` Max value: `1000` An example: if the `granularity` in the request body is set to `day`, Branch will pull results up to the limit for each day. So if the limit is set to `1000` and 5 days' worth of data is queried, then this API will return up to 5000 results.	No
`after`	Integer	A pagination parameter that indicates the index of the first result to return in the response. Default value: `0` An example: In a query with 100 results returned, setting `after` to `50` would return elements 51-100.	No
`query_id`	String	Value passed for this parameter get returned as a query parameter within the `paging` object. Default value: `null` This parameter locks the last event to include in a query, so new events that occur between queries are not added to the results. This prevents count change over time. Note: The `query_id` parameter should be treated as temporary and should only be used when retrieving pages of an existing query where the pagination URLs already have `query_id` set as a parameter. Do not attempt to change the `query_id` between requests or to include a `query_id` with a different query request.	No

Request Body Parameters

Parameter	Type	Description	Required
`start_date`	Date	A timestamp representing the oldest date to return data for. Timezone of the timestamp is set in your Branch Dashboard configuration. Format is an ISO-8601 compliant date-time string, for example: `"2024-01-20"`	Yes
`end_date`	Date	A timestamp representing the most recent date to return data for. Timezone of the timestamp is set in your Branch Dashboard configuration. No events triggered after `end_date` will be counted in the query results. The `end_date` parameter cannot be more than 7 days after the `start_date` parameter. Format is an ISO-8601 compliant date-time string, for example: `"2024-01-20"`	Yes
`data_source`	String	The type of event to query for, prefixed with the source. For example, the source `eo` combined with the `open` event type come together to make `eo_open`, which pulls Branch app opens. Valid Branch data source values: `eo_impression` `eo_click` `xx_impression` `xx_click` `eo_branch_cta_view` `eo_sms_sent` `eo_open` `eo_install` `eo_reinstall` `eo_web_session_start` `eo_pageview` `eo_commerce_event` `eo_custom_event` `eo_content_event` `eo_dismissal` `eo_user_lifecycle_event` `cost`	Yes
`aggregation`	String	How to count events towards the final result count. Possible aggregation values: `unique_count` `total_count` `revenue` `cost` `cost_in_local_currency` Note: When using `unique_count`, each event is only counted if an event triggered by that user has not already been seen. For example, if 10 users each trigger 3 opens, only 10 open events will be counted.	Yes
`dimensions`	Array of Strings	List of event fields to use as splits for the query. Results counts are returned and grouped with other events with matching values for each key provided in `dimensions`. See the Dimensions section for a complete list.	Yes
`filters`	Array of Strings	An object where each key is a valid `dimension`, and each value is an array of string values to check against. If a key is prefixed with a `!`, then any event with that dimension value will be excluded. Otherwise, only events with dimension values matching the filter will be counted. See the Example Queries section for examples of the `filters` array. Also see the Dimensions section for a complete list of valid key values. Any key may be used with the `!` prefix.	No
`enable_install_recalculation`	Boolean	De-dupe unattributed installs caused by duplicate events from non-opt-in users coming from paid ads. This parameter is related to iOS 14.5 privacy changes.	No
`granularity`	String	Range of time to roll multiple events into a single result count. For example, with a `granularity` value of `day`, the counts for each day are returned independently, whereas `all` would return a single count for the entire time range. Possible values: `all` `day` Default value: `all` Note: When you set `all` for this key, Branch will return the data grouped by `start_date`. The `start_date` shown is for the start of the range, and does not mean that data is limited to just that day.	No
`ordered_by`	String	The result key to sort results by. Only 1 sort key is supported. Possible values include any `dimensions` value or the value of `aggregation`. Possible numerical sorting values: - `unique_count` - `total_count` - `revenue` Possible chronological sorting values: - `timestamp` Possible lexicographical sorting values: - All others Note: It is not possible to provide an explicit sort method to the query, so the sort type is chosen automatically based on the value of this `ordered_by` parameter. Behavior for comparison of equal values is left undefined, and as such, the sort is not considered order stable for identical values.	No
`ordered`	String	The direction by which to order the results. Possible values: `ascending` `descending` Default values: `descending`	No
`zero_fill`	Boolean	Whether to return result objects where the result count is 0. If set to `false`, empty results will be omitted from the response. If `true`, fields for empty results will be loaded with `null` or `0` to provide a schema. See the Example Queries section for an example of how this flag works.	No

Response Info

Response Body Parameters

Parameter	Type	Description
`results`	List of Objects	A list of JSON objects that contain result information.
`result`	Object	A JSON object containing the queried values, for example `attributed` or `total_count`. Nested inside `results`, alongside `timestamp`.
`timestamp`	Date	The date and time when the data related to the `result` was created. Nested inside `results`, alongside `result`.
`paging`	Object	A JSON object that includes the total number of results from the query, called `total_count`. This object will also include the number that the results are limited to, if that was included in the request. See `limit` and `after` in the Request Query Parameters section for further information.

Example Request & Response

Total Installs

Below is an example of a basic query that pulls total number of installs per day, split by whether attributed is true or false. The number of results is limited to 5.

curl -X POST -H "Content-Type: application/json" -d '{
  "branch_key":"<YOUR_BRANCH_KEY>",
  "branch_secret":"<YOUR_BRANCH_SECRET>",
  "start_date": "2022-03-01",
  "end_date": "2022-03-07",
  "data_source": "eo_install",
  "dimensions": [
    "attributed"
  ],
  "enable_install_recalculation": true,
  "granularity": "day",
  "aggregation": "total_count"
}' "https://api2.branch.io/v1/query/analytics?limit=5"

{
    "results": [{
        "result": {
            "attributed": "false",
            "total_count": 44
        },
        "timestamp": "2022-03-05T00:00:00.000Z"
    }, {
        "result": {
            "attributed": "false",
            "total_count": 23
        },
        "timestamp": "2022-03-07T00:00:00.000Z"
    }, {
        "result": {
            "attributed": "true",
            "total_count": 14
        },
        "timestamp": "2022-03-05T00:00:00.000Z"
    }, {
        "result": {
            "attributed": "false",
            "total_count": 12
        },
        "timestamp": "2022-03-03T00:00:00.000Z"
    }, {
        "result": {
            "attributed": "false",
            "total_count": 10
        },
        "timestamp": "2022-03-02T00:00:00.000Z"
    }],
    "paging": {
        "next_url": "/v1/query/analytics?limit=5&after=5",
        "total_count": 13
    }
}

See Example Queries for more examples.

Appendix

Dimensions

General Information

Dimension	Description
`"name"`	Name.
`"origin"`	Origin of the data.
`"timestamp"`	Timestamp of the data.
`"deep_linked"`	Is the data deep linked? Can be `true` or `false`.
`"from_desktop"`	Is the data from desktop? Can be `true` or `false`.
`"attributed"`	Is the data attributed? Can be `true` or `false`.

User Information

Dimension	Description
`"user_data_app_store"`	User's app store. Not applicable to the following data source options: `eo_impression`, `eo_click`, `xx_impression`, `xx_click`, `eo_branch_cta_view`, `eo_sms_sent`, `eo_web_session_start`, `eo_pageview`, `eo_dismissal`, `cost`
`"user_data_os"`	User's operating system.
`"user_data_language"`	User's language.
`"user_data_platform"`	User's platform.
`"user_data_environment"`	User's environment.
`"user_data_geo_dma_code"`	User's geographical Designated Market Area code.
`"user_data_geo_country_code"`	User's country code.
`"user_data_country"`	User's country.
`"user_data_geo_region_en"`	User's region.
`"user_data_opted_in"`	Is user opted in?
`"user_data_opted_in_status"`	User's opt-in status.

Custom Event Information

Dimension	Description
`"event_data_custom_param_1"` `"event_data_custom_param_2"` `"event_data_custom_param_3"`	Available dimensions for custom event data. Not applicable to the following data source options: `eo_impression`, `eo_click`, `xx_impression`, `xx_click`, `eo_branch_cta_view`, `eo_sms_sent`, `eo_pageview`, `eo_dismissal`, `cost`

Click & Impression Source Definitions

Data Source	Description
`"eo_impression"`	Real-time user device-level impressions and ad-views triggered via Impression Tracking Ad Links. SAN ad partner's impressions are not included in this data source.
`"eo_click"`	Real-time user device-level Branch Link clicks. 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 as well as SAN ad partner impressions passed to Branch from SAN servers.
`"xx_click"`	Combined aggregated data source containing both real-time user device-level Branch Link clicks as well as the SAN ad partner's clicks passed to Branch from SAN servers.

SAN Ad Partners list:

Facebook
Google Ads
X (formerly Twitter)
Snap
Apple Search Ads
TikTok

Example Queries

Installs Per Day Per OS

This query pulls installs per day and splits the results by OS of the device the user installed on. It limits the number of results to 5.

curl -X POST -H "Content-Type: application/json" -d '{
  "branch_key":"<YOUR_BRANCH_KEY>",
  "branch_secret":"<YOUR_BRANCH_SECRET>",
  "start_date": "2017-12-12",
  "end_date": "2017-12-18",
  "data_source": "eo_install",
  "dimensions": [
    "user_data_os"
  ],
  "enable_install_recalculation": true,
  "granularity": "day",
  "aggregation": "total_count"
}' "https://api2.branch.io/v1/query/analytics?limit=5"

{
  "results": [
    {
      "result": {
        "user_data_os": "ANDROID",
        "total_count": 144
      },
      "timestamp": "2017-12-18T00:00:00.000Z"
    },
    {
      "result": {
        "user_data_os": "IOS",
        "total_count": 142
      },
      "timestamp": "2017-12-18T00:00:00.000Z"
    },
    {
      "result": {
        "user_data_os": "IOS",
        "total_count": 191
      },
      "timestamp": "2017-12-17T00:00:00.000Z"
    },
    {
      "result": {
        "user_data_os": "ANDROID",
        "total_count": 194
      },
      "timestamp": "2017-12-17T00:00:00.000Z"
    },
    {
      "result": {
        "user_data_os": "ANDROID",
        "total_count": 246
      },
      "timestamp": "2017-12-16T00:00:00.000Z"
    }
  ],
  "paging": {
    "next_url": "/v1/query/analytics?query_id=CqdBOb&limit=5&after=5",
    "total_count": 14
  }
}

Unique Click Counts

Below is a more complex query for pulling unique click counts. These counts are split out by 4 different dimensions.

This query also has a filter, which filters out any clicks where last_attributed_touch_data_plus_current_feature was MOBILE_DEEPVIEWS or DESKTOP_DEEPVIEWS.

A maximum of 5 results will be returned, in descending order of unique_count. Results with days that had 0 clicks will be returned (and not filtered out) because the zero_fill flag is set to true:

curl -X POST -H "Content-Type: application/json" -d '{
  "branch_key":"<YOUR_BRANCH_KEY>",
  "branch_secret":"<YOUR_BRANCH_SECRET>",
  "start_date": "2017-12-12",
  "end_date": "2017-12-18",
  "data_source": "eo_click",
  "dimensions": [
    "last_attributed_touch_data_tilde_feature",
    "last_attributed_touch_data_tilde_channel",
    "last_attributed_touch_data_tilde_campaign",
    "last_attributed_touch_data_plus_current_feature"
  ],
  "filters": {
    "!last_attributed_touch_data_plus_current_feature": [
      "MOBILE_DEEPVIEWS",
      "DESKTOP_DEEPVIEWS"
    ]
  },
  "ordered": "descending",
  "ordered_by": "unique_count",
  "aggregation": "unique_count",
  "zero_fill": true
}' "https://api2.branch.io/v1/query/analytics?limit=5"

{
  "results": [
    {
      "timestamp": "2017-12-12T00:00:00.000Z",
      "result": {
        "last_attributed_touch_data_tilde_channel": "ads",
        "last_attributed_touch_data_tilde_campaign": "Xmas",
        "last_attributed_touch_data_tilde_feature": "paid advertising",
        "last_attributed_touch_data_plus_current_feature": "ADS",
        "unique_count": 750
      }
    },
    {
      "timestamp": "2017-12-12T00:00:00.000Z",
      "result": {
        "last_attributed_touch_data_tilde_channel": "taptica#1",
        "last_attributed_touch_data_tilde_campaign": "taptica#1",
        "last_attributed_touch_data_tilde_feature": "paid advertising",
        "last_attributed_touch_data_plus_current_feature": "ADS",
        "unique_count": 723
      }
    },
    {
      "timestamp": "2017-12-12T00:00:00.000Z",
      "result": {
        "last_attributed_touch_data_tilde_channel": "Journeys",
        "last_attributed_touch_data_tilde_campaign": "Default Banner",
        "last_attributed_touch_data_tilde_feature": "journeys",
        "last_attributed_touch_data_plus_current_feature": "MOBILE_JOURNEYS",
        "unique_count": 553
      }
    },
    {
      "timestamp": "2017-12-12T00:00:00.000Z",
      "result": {
        "last_attributed_touch_data_tilde_channel": "Apple App Store",
        "last_attributed_touch_data_tilde_campaign": null,
        "last_attributed_touch_data_tilde_feature": "paid advertising",
        "last_attributed_touch_data_plus_current_feature": "ADS",
        "unique_count": 432
      }
    },
    {
      "timestamp": "2017-12-12T00:00:00.000Z",
      "result": {
        "last_attributed_touch_data_tilde_channel": null,
        "last_attributed_touch_data_tilde_campaign": null,
        "last_attributed_touch_data_tilde_feature": "marketing",
        "last_attributed_touch_data_plus_current_feature": "QUICK_LINKS",
        "unique_count": 201
      }
    }
  ],
  "paging": {
    "next_url": "/v1/query/analytics?query_id=EDdBOb&limit=5&after=5",
    "total_count": 143
  }
}

Include or Omit Response Objects

When zero_fill is set to true, response objects with a total_count equal to 0 will be returned alongside other results:

{
    "branch_key":"<YOUR BRANCH KEY>",
    "branch_secret":"<YOUR BRANCH SECRET>",
    "start_date": "2022-02-01",
    "end_date": "2022-02-01",
    "data_source": "xx_click",
    "dimensions": [
            "last_attributed_touch_data_tilde_advertising_partner_name",
            "last_attributed_touch_data_tilde_campaign_id"
    ],
    "ordered": "descending",
    "aggregation": "total_count",
    "zero_fill": true 
}

{
    "result": {
        "last_attributed_touch_data_tilde_advertising_partner_name": "Google AdWords",
        "last_attributed_touch_data_tilde_campaign_id": "78726498102",
        "total_count": 1
    },
    "timestamp": "2022-02-01T00:00:00.000+08:00"
},
{
    "result": {
        "last_attributed_touch_data_tilde_advertising_partner_name": "Google AdWords",
        "last_attributed_touch_data_tilde_campaign_id": "87192837612",
        "total_count": 1
    },
    "timestamp": "2022-02-01T00:00:00.000+08:00"
}
{
    "result": {
        "last_attributed_touch_data_tilde_advertising_partner_name": "Google AdWords",
        "last_attributed_touch_data_tilde_campaign_id": "17384628491",
        "total_count": 0
    },
    "timestamp": "2022-02-01T00:00:00.000+08:00"
}

When zero_fill is set to false, response objects with a total_count equal to 0 are omitted:

{
    "branch_key":"<YOUR BRANCH KEY>",
    "branch_secret":"<YOUR BRANCH SECRET>",
    "start_date": "2022-02-01",
    "end_date": "2022-02-01",
    "data_source": "xx_click",
    "dimensions": [
            "last_attributed_touch_data_tilde_advertising_partner_name",
            "last_attributed_touch_data_tilde_campaign_id"
    ],
    "ordered": "descending",
    "aggregation": "total_count",
    "zero_fill": false 
}

{
    "result": {
        "last_attributed_touch_data_tilde_advertising_partner_name": "Google AdWords",
        "last_attributed_touch_data_tilde_campaign_id": "78726498102",
        "total_count": 1
    },
    "timestamp": "2022-02-01T00:00:00.000+08:00"
},
{
    "result": {
        "last_attributed_touch_data_tilde_advertising_partner_name": "Google AdWords",
        "last_attributed_touch_data_tilde_campaign_id": "87192837612",
        "total_count": 1
    },
    "timestamp": "2022-02-01T00:00:00.000+08:00"
}

Overview

Benefits

Limits

Try It!

Getting Started

Prerequisites

Access

General Access

Agency Access

🚧Agency-Tagged Data

Authentication

Usage

Post Query

Request Info

Export Request

Request Headers

Request Query Parameters

Request Body Parameters

Response Info

Response Body Parameters

Example Request & Response

Total Installs

Appendix

Dimensions

General Information

User Information

Custom Event Information

Click & Impression Source Definitions

SAN Ad Partners list:

Example Queries

Installs Per Day Per OS

Unique Click Counts

Include or Omit Response Objects

🚧
Agency-Tagged Data