Aggregate API

Export log-level and aggregate-level data for measuring campaign performance.

Get export download status

GET/analytics/{job_id}

Check the status of an aggregate export job. When the job's status is FINISHED, the response includes a signed response_url you can use to download the export.

Parameters

app_idstringqueryRequired
Unique identifier for the Branch app of the requested data.
job_idstringpathRequired
The unique ID of the request. Obtained from the Export Request.
formatenumquery
Format of the returned data: json or csv.
csvjson
limitintegerquery
The maximum number of results to return.

Returns

Current status of the aggregate export job. When status is FINISHED, response_url contains the signed download link. Returns 400, 404, and 429 on failure — see the response panel for the error shape.

job_id*app_id*limitformatAccess-Token*

curl 'https://api2.branch.io/v2/analytics/a1b2c3d4?app_id=123456789012345680' \
  --request GET \
  --header 'Access-Token: <Access-Token>'

Response

Current status of the aggregate export job. When status is FINISHED, response_url contains the signed download link.

{
  "code": 200,
  "status": "FINISHED",
  "response_url": "https://branch-exports-usw2.s3.amazonaws.com/partner-query/2023-05-12-2023-05-19-eo_install-day-{JOB_ID}.csv?Signature={SIGNATURE}&AWSAccessKeyId={AWS_KEY}&Expires={EXPIRATION}"
}

Request aggregate export

POST/analytics

By passing in the appropriate options, you can initiate an export of your aggregate Branch data.

Parameters

data_sourceenumRequired
A string value representing the data source. See Topics for the complete list.
eo_impressioneo_clickeo_web_to_app_auto_redirecteo_branch_cta_vieweo_openeo_installeo_reinstalleo_web_session_starteo_pagevieweo_commerce_eventeo_custom_eventeo_content_event
dimensionsarray of enumRequired
An array representing the dimensions to group by. The limit is 11. See Dimensions for the complete list.
nameapp_idapp_nameorigintimestampdeep_linkedfrom_desktopattributeduser_data_app_storeuser_data_app_versionuser_data_osuser_data_language
end_datestringRequired
The end of the interval time range represented as an ISO-8601 complete date.
start_datestringRequired
The start of the interval time range represented as an ISO-8601 complete date.
aggregationenum
How to count events toward the final result count. When querying with a data source of "eo_commerce_event", the aggregation may also be specified as "revenue", in which case the counts returned are the sum of revenue from matching events, and not the number of events themselves.
unique_counttotal_countrevenuecostcost-in-local-currency
enable_install_calculationboolean
If true, then Branch will dedupe unattributed installs caused by duplicate events from non-opt-in users coming from paid ads (resulting from iOS 14.5 privacy changes).
filtersobjectExpandable
Keys are the same as dimensions. Values are an array of values to match for the dimension.
An object defining filters to match or disallow certain values.
formatenumquery
Format of the returned data: json or csv.
csvjson
granularityenum
The time granularity that each band value will represent.
dayweekmonth
limitintegerquery
The maximum number of results to return.

Returns

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

limitformatapp_id*Access-Token*

curl 'https://api2.branch.io/v2/analytics?app_id=%3Capp_id%3E' \
  --request POST \
  --header 'Access-Token: <Access-Token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "start_date": "2023-05-15",
    "end_date": "2023-05-16",
    "data_source": "eo_install",
    "dimensions": [
      "user_data_os"
    ],
    "granularity": "day",
    "aggregation": "total_count",
    "filters": {
      "attributed": "true",
      "user_data_os": [
        "IOS",
        "ANDROID"
      ]
    }
  }'

Response

Status of aggregate export.

{
  "code": 200,
  "job_id": "XXXX-0000-xxxx",
  "status_url": "https://api2.branch.io/v2/analytics/a1b2c3d4"
}