查询（Query） API

频率限制

• 每秒5个请求
• 每分钟20个请求
• 每小时150个请求

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

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

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

如果需要更多记录，请以较短的时间间隔进行多次请求，以将必要的数据放入“批次”中。

Export Window

Rolling 2 year window

Specific Dimension Combinations

Combining the following dimensions together will result in an error being returned when pulling SAN cost, click, and impression data (data_source = cost， xx_click, or xx_impression):

• user_data_os + user_data_geo_country_code
• last_attributed_touch_data_tilde_secondary_publisher + user_data_geo_country_code

branch_key

String

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

是

branch_secret

String

The Branch secret of the app used for authentication.

是

limit

Integer

The maximum number of results to return in the response. If the granularity 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, with granularity=day, then this API will return up to 5000 results.

• Default Value: 100
• Max Value: 1000

否

after

Integer

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

• Default Value: 0

否

query_id

String

Returned as a 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).

• Default Value: null

Note: The query_id 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 query parameter. You should not attempt to change the id between requests or include a query_id with a different query request.

start_date

Date

A timestamp representing the oldest date to return data for. Timezone of the timestamp is set in your Branch Dashboard configuration.

是

end_date

Date

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.

• Cannot be more than 7 days after the startdate
• Format: An ISO-8601 compliant date-time string. Eg: "2020-01-20"

是

data_source

String

The type of event to query for, prefixed with the source (eg 'eo' + 'open' 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"

是

aggregation

String

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. E.g., if 10 users each trigger 3 opens, only 10 open events will be counted.

Possible Values:

• "unique_count"
• "total_count"
• "revenue"
• "cost"
• "cost_in_local_currency"

是

维度

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 Dimensions for a complete list.

是

筛选

Array of Strings

An object where each key is a valid "dimension", and each value is an array of string values. If a key is prefixed with a '!', then any event with a dimension value contained in the value of that key is excluded. Otherwise, only events with dimension values matching the filter will be counted.

Example:

{  "filters": {    "last_attributed_touch_data_plus_current_feature": [      "MOBILE_DEEPVIEWS",      "DESKTOP_DEEPVIEWS"    ],    "!user_data_os": [ "iOS" ]  }}

this would count only events where:

• lastattributed_touch_data_plus_current_feature was equal to "MOBILE_DEEPVIEWS" or "DESKTOP_DEEPVIEWS"
  and
• userdata_os was not equal to "iOS"

Possible Keys: See Dimensions for valid key values. Any key may also be used with a "!" prefix

否

enable_install_recalculation

Boolean

De-dupe unattributed installs caused by duplicate events from non-opt-in users coming from paid ads (result from iOS 14.5 privacy changes).

否

granularity

String

Range of time to roll multiple events into a single result count. E.g., with a 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 Values: "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 it does not mean that data is limited to just that day.

否

ordered_by

String

The result key to sort results by. Only 1 sort key is supported.

Possible Values: Any element of query "dimensions" or the value of "aggregation" in the query.

Note: Sorts and the ordered_by parameter:

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 "ordered_by". Behavior for comparison of equal values is left undefined, and as such, the sort is not considered order stable for identical values.

Values for "ordered_by" Sort:

Numerically Sorted:

• "unique_count"
• "total_count
• "revenue"

Chronologically Sorted:

• "timestamp"

Lexicographically Sorted:

• everything else

否

ordered

String

The direction to order the results.

Possible Values:

• "ascending"
• "descending"

Default Value: "descending"

否

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.