Query API

The Query API is an HTTP API that you can use to programmatically query pre-aggregated analytics.

Read the Query API overview

Post query

POST/query/analytics

This endpoint lets you query dashboard analytics without having to access Branch.

Parameters

aggregationenumRequired
How to count events toward the final result count. When using unique_count, each event is only counted if an event by that user hasn't already been seen.
unique_counttotal_countrevenuecostcost_in_local_currency
branch_keystringRequired
The Branch Key of the app you're pulling analytics information for.
branch_secretstringRequired
The Branch Secret of the app, used for authentication.
data_sourceenumRequired
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 aren't 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 aren't 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 real-time user-device level clicks and the SAN Ad Partner's clicks passed to Branch systems from SAN servers.
eo_impressioneo_clickxx_impressionxx_clickeo_web_to_app_auto_redirecteo_branch_cta_vieweo_openeo_installeo_reinstalleo_web_session_starteo_pagevieweo_commerce_event
dimensionsarray of enumRequired
List of event fields to use as splits for the query. Result counts are returned grouped with other events that have matching values for each key provided in dimensions.
nameorigintimestampdeep_linkedfrom_desktopattributedlast_attributed_touch_typelast_attributed_touch_data_tilde_tagslast_attributed_touch_data_tilde_secondary_publisherlast_attributed_touch_data_plus_current_featurelast_attributed_touch_data_plus_via_featureslast_attributed_touch_data_tilde_campaign
end_datestringRequired
The last timestamp (exclusive) to return data for. No events that triggered after the end_date will be counted in the query results. The time zone of the timestamp is set in your Branch configuration. Note that end_date can't be more than 7 days after the start_date.
start_datestringRequired
A timestamp representing the oldest date to return data for. The time zone of the timestamp is set in your Branch configuration. Note that start_date can't be earlier than 2017-10-14.
afterintegerquery
A pagination parameter indicating the index of the first result to return in the response. For example, with 100 results returned, setting "after" to 50 would return elements 51-100.

More parameters

enable_install_recalculationboolean
filtersobject
granularityenum
limitintegerquery
orderedenum
ordered_byenum
query_idstringquery
zero_fillboolean

Returns

Status of aggregate export. Returns 400 and 429 on failure — see the response panel for the error shape.

limitafterquery_id

curl 'https://api2.branch.io/v1/query/analytics' \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
    "branch_key": "key_live_xxxx",
    "branch_secret": "secret_live_xxxx",
    "start_date": "2023-05-01",
    "end_date": "2023-05-07",
    "data_source": "eo_install",
    "aggregation": "total_count",
    "dimensions": [
      "attributed"
    ],
    "filters": {
      "!last_attributed_touch_data_plus_current_feature": [
        "MOBILE_DEEPVIEWS",
        "DESKTOP_DEEPVIEWS"
      ]
    },
    "granularity": "all",
    "ordered_by": "attributed",
    "ordered": "descending"
  }'

Response

Status of aggregate export.

{
  "results": [
    {
      "result": {
        "attributed": "true",
        "total_count": 129
      },
      "timestamp": "2023-05-01T00:00:00.000-08:00"
    },
    {
      "result": {
        "attributed": "true",
        "total_count": 125
      },
      "timestamp": "2023-05-04T00:00:00.000-08:00"
    },
    {
      "result": {
        "attributed": "false",
        "total_count": 95
      },
      "timestamp": "2023-05-04T00:00:00.000-08:00"
    }
  ],
  "paging": {
    "next_url": "/v1/query/analytics?limit=5&after=3",
    "total_count": 14
  }
}