Custom Exports API

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

Read the Custom Exports API overview

Get export request

GET/logs/{request_handle}

Retrieves custom export request logs based on the provided request handle ID.

Parameters

request_handlestringpathRequired
The ID returned by the log export queue.
formatenumquery
Format of the returned data: json or csv.
csvjson
limitintegerquery
The maximum number of results to return.

Returns

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

request_handle*limitformatapp_id*Access-Token*

curl 'https://api2.branch.io/v2/logs/a1b2c3d4?app_id=%3Capp_id%3E' \
  --request GET \
  --header 'Access-Token: <Access-Token>'

Response

Status of aggregate export.

{
  "status": "complete",
  "response_url": "https://branch-exports-web-usw2.s3.us-west-1.amazonaws.com/v2/y%3D2023/m%3D05/d%3D17/app_id%3D{APP_ID}/job_id%3Da1b2c3d4/task_id%3D{TASK_ID}/unique-csv-file-name-here.csv?X-Amz-Algorithm={AMZ_ALGORITHM}&X-Amz-Date={AMZ_DATE}&X-Amz-SignedHeaders={AMZ_SIGNED_HEADERS}&X-Amz-Expires={AMZ_EXPIRATION}&X-Amz-Credential={AMZ_CREDENTIAL}&X-Amz-Signature={AMZ_SIGNATURE}",
  "lines_exported": 0,
  "code": 200
}

Check data readiness

POST/data/ready

Check if event or aggregate data is ready and available for a topic, for a particular hour of the day.

Parameters

app_idintegerRequired
Your Branch app ID, found under Account Settings in Branch.
datestringRequired
The start of the interval time range, in the format YYYY-MM-DD hh:mm:ss (must be within the past year).
topicenumRequired
The topic associated with the data.
eo_impressioneo_clickeo_branch_cta_vieweo_openeo_installeo_reinstalleo_web_session_starteo_pagevieweo_commerce_eventeo_custom_eventeo_content_eventeo_dismissal
warehouse_meta_typeenumRequired
The type of data to check for.
EVENTAGGREGATE

Returns

Data readiness status successfully retrieved. Returns 400, 429, and 500 on failure — see the response panel for the error shape.

app_id*Access-Token*

curl 'https://api2.branch.io/v2/data/ready?app_id=%3Capp_id%3E' \
  --request POST \
  --header 'Access-Token: <Access-Token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "date": "2024-01-05 01:00:00",
    "warehouse_meta_type": "EVENT",
    "topic": "eo_open",
    "app_id": 0
  }'

Response

Data readiness status successfully retrieved.

{
  "data_ready": true,
  "date": "2024-01-05 01:00:00"
}

Create export request

POST/logs

By passing in the appropriate options, you can find and queue all records that match search criteria for export and build the relevant export request accordingly.

Parameters

end_datestringRequired
The end of the interval time range represented as an ISO-8601 complete datetime including hours, minutes, seconds, and milliseconds.
fieldsarray of enumRequired
An array representing fields/columns available in your report. To include every available field, use ["all"] instead of a field list. The all-fields option requires Sensitive Data, Fraud Settings & Data, and Export permissions. When using "all", new fields are automatically included as they become available—design your systems to handle schema changes gracefully. See Available EO Fields for the complete list.
allapp_idapp_nameattributedcontent_itemscustom_datacustomer_event_aliasdays_from_last_attributed_touch_to_eventdeep_linkeddi_match_click_tokenevent_data_ad_typeevent_data_affiliation
limitintegerRequired
The maximum number of results to return.
report_typeenumRequired
An array representing the event type of your report. See Available Topics for the complete list.
eo_impressioneo_clickeo_branch_cta_vieweo_openeo_installeo_reinstalleo_web_session_starteo_pagevieweo_commerce_eventeo_custom_eventeo_content_eventeo_dismissal
start_datestringRequired
The start of the interval time range represented as an ISO-8601 complete datetime including hours, minutes, seconds, and milliseconds. Datetime must be within the last 120 days.
allow_multiple_filesboolean
Set this parameter to true if you want more than 15 million records returned.
filterarray of string
A filter requires an array with 3 specific string values: "[Filter Prefix", "EO Field Key", "EO Field Value"]
response_formatenum
Format of the returned data: json or csv.
csvjson
response_format_compressionenum
The file compression method to use for the data. Required if allow_multiple_files is set to true.
gzsnappy
timezoneenum
Time zone for results. Accepts tz database strings such as 'America/Los_Angeles'. Results are returned in the time zone set in Branch if you don't provide one. Defaults to UTC only if no time zone is set in Branch.
Africa/AbidjanAfrica/AccraAfrica/Addis_AbabaAfrica/AlgiersAfrica/AsmaraAfrica/AsmeraAfrica/BamakoAfrica/BanguiAfrica/BanjulAfrica/BissauAfrica/BlantyreAfrica/Brazzaville

Returns

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

app_id*Access-Token*

curl 'https://api2.branch.io/v2/logs?app_id=%3Capp_id%3E' \
  --request POST \
  --header 'Access-Token: <Access-Token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "start_date": "2023-05-15T00:00:00Z",
    "end_date": "2023-05-15T01:59:59Z",
    "report_type": "eo_open",
    "fields": [
      "name"
    ],
    "limit": 100,
    "timezone": "America/Los_Angeles",
    "filter": [
      "eq",
      "name",
      "PURCHASE"
    ],
    "response_format": "csv",
    "response_format_compression": "gz"
  }'

Response

Status of aggregate export.

{
  "handle": "xxxx-0000",
  "export_job_status_url": "https://api2.branch.io/v2/logs/{JOB_HANDLE}?app_id={APP_ID}"
}