Cross-Events Export API

Query and compare vast pools of data across multiple sources.

Read the Cross-Events Export API overview

Get export download status

GET/branch_aggregate/async/status/{job_id}

Receive a status update on your aggregate export request, as well as a URL to the data.

Parameters

app_idstringqueryRequired
The unique identifier for the app. Alternatively, provide organization_id.
job_idstringpathRequired
The unique ID of the request. Obtained from the export request.

Returns

Job successfully finished. Returns 400, 404, and 429 on failure — see the response panel for the error shape.

job_id*app_id*Access-Token*

curl 'https://api2.branch.io/v1/branch_aggregate/async/status/a1b2c3d4?app_id=123456789012345680' \
  --request GET \
  --header 'Access-Token: <Access-Token>'

Response

Job successfully finished.

{
  "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 data export

POST/branch_aggregate/async/analytics

Initiate an export of your aggregate Branch data.

Parameters

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.
aggregationsarray of object
An array where each element is an aggregation object. An aggregation object requires a field name, a display name, and a data source. See schema and more.
dimensionsarray of enum
An array representing the dimensions to group by. See the dimensions section for more.
link_aliaslink_archivedlink_creation_sourcelink_dollar_sign_3plink_dollar_sign_android_deeplink_pathlink_dollar_sign_android_deepviewlink_dollar_sign_android_passive_deepviewlink_dollar_sign_android_urllink_dollar_sign_canonical_identifierlink_dollar_sign_canonical_urllink_dollar_sign_deeplink_pathlink_dollar_sign_desktop_deeplink_path
filterobject
An object representing a filter or multiple filters. See filter examples.
granularityenum
The time granularity that each band value will represent.
dayweekmonthall
limit_sort_specobject
An object describing column/row ordering and limiting. See schema.
response_formatenum
Compression format to use for the data file.
parquetcsvjson
response_format_compressionenum
Compression method to use for the data file.
snappygz

Returns

Success. Returns 400 and 429 on failure — see the response panel for the error shape.

app_id*Access-Token*

curl 'https://api2.branch.io/v1/branch_aggregate/async/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",
    "dimensions": [
      "user_data_os"
    ],
    "filter": {
      "type": "in",
      "dimension": "name",
      "values": [
        "x",
        "y"
      ]
    },
    "granularity": "all",
    "limit_sort_spec": {
      "sort_columns": []
    },
    "aggregations": [
      {
        "field_name": "sketch_unique_count",
        "display_name": "unique_lifecycle_events_count",
        "data_source": "eo_user_lifecycle_event"
      },
      {
        "field_name": "total_count",
        "display_name": "eo_click",
        "data_source": "eo_click"
      }
    ],
    "response_format_compression": "snappy",
    "response_format": "parquet"
  }'

Response

Success.

{
  "code": 200,
  "job_id": "XXXX-0000-xxxx",
  "status_url": "https://api2.branch.io/v1/branch_aggregate/async/status/a1b2c3d4"
}