Query API Overview

  • Published on Mar 20, 2025

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 hourIf 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_code2. 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:

  1. Create a Branch Dashboard.

  2. Enable Universal Ads and start running ad campaigns from your Branch account.

  3. Implement the appropriate Branch SDK into your mobile app (iOS | Android).

  4. 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:

  1. In the left-hand navigation, under Setup & Testing, 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 Aggregate Data box.

  5. Add data filters (optional):

    1. Under Data Filters, toggle any necessary data filters on/blue. Exported data will be filtered accordingly.

  6. Click Save.

1246

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
- revenuePossible chronological sorting values:

- timestampPossible lexicographical sorting values:

- All othersNote: 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_app_version

User's version of the app.

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"
}