Scheduled Log Exports API Reference
Full reference for the Schedule Log Exports API
Beta API
This API is in beta and is available to enterprise customers only. If you would like to use this feature, please reach out to your Branch account team.
Please visit the Scheduled Log Exports API Guide to get started quickly!
Set Up a New Subscription
Endpoint: POST /scheduled-exports/logs/subscribe
Set up a new scheduled log export subscription. Supported at both app and org level. The result is a subscription that specifies what data will be exported (e.g. topic, columns, filters) and where data will be exported to (e.g. email addresses, your cloud data bucket, a Branch-hosted S3 bucket).
NOTE: In order to prevent duplicate active subscriptions being created accidentally, we will throw an error if you attempt to create a subscription that exactly matches an existing subscription based on the following values: subscription_type, report_type, app_id or organization_id, fields, filter, cadence
. Even re-ordering the values in fields
is enough to bypass this check and create a new subscription.
New Subscription with Data Stored in Branch's S3 Bucket
For this type of subscription, you'll set destination.subscription_type = "branch"
.
Request Headers
Header | Description | Required |
---|---|---|
| your Access Token. Created on the Branch dashboard, associated with one user. Can be retrieved from the User page of the Dashboard — learn more here. | YES |
| information about the report that should be generated. | n/a |
| how frequently the report is generated, and for what time period it is generated. Options: | YES |
| format in which the export data is delivered. Options: | YES |
| method by which the export data should be compressed. Options: | NO |
| data source from which data should be exported. See the Custom Export API's list of Branch Available Topics. | YES |
| fields (e.g. CSV columns) which should be exported. See the Custom Export API's list of Branch Available EO Fields. | YES |
| filter used to reduce which data points (e.g. CSV rows) which should be exported. See the Custom Export API's Cthulhu Filter Specification. | NO |
| information about where a finished report is stored and how it can be accessed | n/a |
| should be set to | YES |
Example Request:
curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' \
-H 'access-token: api_app_99999999999999999999999999999999' -d '{
"report": {
"cadence": "hourly",
"response_format": "csv",
"response_format_compression": "gz",
"report_type": "eo_install",
"report_fields": [
"id",
"timestamp",
"user_data_os",
"user_data_idfa",
"user_data_idfv",
"user_data_aaid"
],
"filter": [
"eq",
"attributed",
"true"
]
},
"destination": {
"subscription_type": "branch"
}
}' 'https://api2.branch.io/scheduled-exports/logs/subscribe?app_id=123456789009876543'
Response Body Parameters
Parameter | Description |
---|---|
| a persistent id for this subscription, used to check the status, locate recent export jobs, and make modifications |
| if |
| more information about the subscription's status. |
| get details on this subscription. See the section "Get details on one log export subscription" below. |
Example Response:
{
"subscription_id": "13dbe05c-175b-11ec-9621-0242ac130002",
"status": "PENDING",
"description": "Generating sample report. Subscription will finish after Report is uploaded",
"subscription_url": "https://api2.branch.io/scheduled-exports/exports/logs/subscription/13dbe05c-175b-11ec-9621-0242ac130002?app_id=123456789009876543"
}
New Subscription with Data Stored in your own Cloud
For this type of subscription, you'll set destination.subscription_type = "cloud"
.
We recommend setting up a new S3 bucket and creating a folder within that bucket for Branch exports. E.g. s3://my-branch-export-bucket/my-folder/
A guide on this can be found here.
Request Headers
Header | Description |
---|---|
| your Access Token. Created on the Branch dashboard, associated with one user. Can be retrieved from the User page of the Dashboard — learn more here. |
Request Body Parameters
Parameter | Description | Required |
---|---|---|
| information about the report that should be generated. | n/a |
| how frequently the report is generated, and for what time period it is generated. Options: | YES |
| format in which the export data is delivered. Options: | YES |
| method by which the export data should be compressed. Options: | NO |
| data source from which data should be exported. See the Custom Export API's list of Branch Available Topics. | YES |
| fields (e.g. CSV columns) which should be exported. See the Custom Export API's list of Branch Available EO Fields. | YES |
| filter used to reduce which data points (e.g. CSV rows) which should be exported. See the Custom Export API's Cthulhu Filter Specification. | NO |
| information about where a finished report is stored and how it can be accessed | N/A |
| should be set to | YES |
| In the future we may support other options beyond AWS S3. | YES |
| the ARN for the AWS Role you are using for Branch exports. E.g. | YES |
| the AWS bucket you are using for Branch exports. Do not include | YES |
| the prefix or folder you are using for Branch exports. E.g. if you are exporting to | YES |
Example Request:
curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' \
-H 'access-token: api_app_99999999999999999999999999999999' -d '{
"report": {
"cadence": "hourly",
"response_format": "csv",
"response_format_compression": "gz",
"report_type": "eo_install",
"report_fields": [
"id",
"timestamp",
"user_data_os",
"user_data_idfa",
"user_data_aaid",
"user_data_idfv"
],
"filter": [
"eq",
"attributed",
"true"
]
},
"destination": {
"subscription_type": "cloud",
"cloud": "s3",
"resource_access_id": "arn:aws:iam::xxxxxxxxxxxx:role/Branch-Export-Upload-tbd",
"bucket": "my-branch-export-bucket",
"prefix": "my-folder"
}
}' 'https://api2.branch.io/scheduled-exports/logs/subscribe?app_id=123456789009876543'
Response Body Parameters
Parameter | Description |
---|---|
| a persistent id for this subscription, used to check the status, locate recent export jobs, and make modifications |
| if |
| more information about the subscription's status. |
| get details on this subscription. See the section "Get details on one log export subscription" below. |
Example Response:
{
"subscription_id": "1d7d7c2e-175b-11ec-9621-0242ac130002",
"status": "PENDING",
"description": "Generating sample report. Subscription will finish after Report is uploaded",
"subscription_url": "https://api2.branch.io/scheduled-exports/logs/subscription/1d7d7c2e-175b-11ec-9621-0242ac130002?app_id=123456789009876543"
}
New Subscription with Links Emailed Out Daily
For this type of subscription, you'll set destination.subscription_type = "email".
Request Headers
Header | Description | Required |
---|---|---|
| your Access Token. Created on the Branch dashboard, associated with one user. Can be retrieved from the User page of the Dashboard — learn more here. | YES |
| information about the report that should be generated. | n/a |
| how frequently the report is generated, and for what time period it is generated. Options: | YES |
| format in which the export data is delivered. Options: | YES |
| method by which the export data should be compressed. Options: | NO |
| data source from which data should be exported. See the Custom Export API's list of Branch Available Topics. | YES |
| fields (e.g. CSV columns) which should be exported. See the Custom Export API's list of Branch Available EO Fields. | YES |
| filter used to reduce which data points (e.g. CSV rows) which should be exported. See the Custom Export API's Cthulhu Filter Specification. | NO |
| information about where a finished report is stored and how it can be accessed | n/a |
| should be set to email if you want links to data emailed to you on a daily basis. The data is stored in Branch's S3 bucket, with links to this data emailed to you daily. This data is also accessible via API (see "Get details on many export jobs" below) | YES |
Example Request:
curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' \
-H 'access-token: api_app_99999999999999999999999999999999' -d '{
"report": {
"cadence": "hourly",
"response_format": "csv",
"response_format_compression": "gz",
"report_type": "eo_install",
"report_fields": [
"id",
"timestamp",
"user_data_os",
"user_data_idfa",
"user_data_idfv",
"user_data_aaid"
],
"filter": [
"eq",
"attributed",
"true"
]
},
"destination": {
"subscription_type": "email",
"recipient_emails": [ "[email protected]" ]
}
}' 'https://api2.branch.io/scheduled-exports/logs/subscribe?app_id=123456789009876543'
Response Body Parameters
Parameter | Description |
---|---|
| a persistent id for this subscription, used to check the status, locate recent export jobs, and make modifications |
| if |
| more information about the subscription's status. |
| get details on this subscription. See the section "Get details on one log export subscription" below. |
Example Response:
{
"subscription_id": "6c13330c-5073-4aba-b96b-800386245363",
"status": "PENDING",
"description": "Generating sample report. Subscription will finish after Report is uploaded",
"subscription_url": "https://api2.branch.io/scheduled-exports/logs/subscription/6c13330c-5073-4aba-b96b-800386245363?app_id=271025631825777235"
}
Deactivate a Subscription
Endpoint: DELETE /scheduled-exports/logs/subscription/{subscription_id}
Deactivates a single export subscription for a given Subscription Id.
Request Headers
Header | Description |
---|---|
| your Access Token. Created on the Branch dashboard, associated with one user. Can be retrieved from the User page of the Dashboard — learn more here. |
Request URL Parameters:
Parameter | Description |
---|---|
| the relevant subscription Id. |
Example Request:
curl -X DELETE -H 'access-token: api_app_99999999999999999999999999999999' \
'https://api2.branch.io/scheduled-exports/logs/subscription/13dbe05c-175b-11ec-9621-0242ac130002?app_id=123456789009876543'
Response Body Parameters
Parameter | Description |
---|---|
| whether the deactivate request succeeded |
| more information about the status of the request |
Example Response:
{
"status": "SUCCESS",
"description": "Subscription deactivated successfully"
}
Retrieve "external Id"
Endpoint: GET /scheduled-exports/logs/subscription/externalId?[app_id|organization_id]={id}
Branch provides a unique "external Id" for your Branch account. This should be used when setting up data to be exported to your cloud data service (i.e. AWS S3).
Request Headers:
Header | Description |
---|---|
| your Access Token. Created on the Branch dashboard, associated with one user. Can be retrieved from the User page of the Dashboard — learn more here. |
Request URL Query Parameters:
Provide one of the following two options:
Parameter | Description |
---|---|
| the app Id with which the Access Token and subscriptions are associated |
| the organization Id with which the Access Token and subscriptions are associated |
Example Request:
curl -H 'access-token: api_app_99999999999999999999999999999999' \
'https://api2.branch.io/scheduled-exports/logs/subscription/externalId?app_id=123456789009876543'
Response Body Parameters:
Parameter | Description |
---|---|
| the ID to be used in the Trust Relationship of the Role that you create to allow Branch to access your S3 bucket. |
Example Response:
{"external_id":"9da763b0-175b-11ec-9621-0242ac130002"}
Get Details on Individual Export Subscription
Endpoint: GET /scheduled-exports/logs/subscription/{subscription_id}
Returns a single export subscription for a given subscription Id. See what data is being exported (e.g. topic, columns, filters) and where data is exported to (e.g. email addresses, your data center, a Branch-hosted S3 bucket).
Request Headers
Header | Description |
---|---|
| your Access Token. Created on the Branch dashboard, associated with one user. Can be retrieved from the User page of the Dashboard — learn more here. |
Request URL Parameters
Parameter | Description |
---|---|
| the relevant subscription Id. |
Request Query Parameters
Provide one of the following two options:
Parameter | Description |
---|---|
| the app Id with which the Access Token and subscriptions are associated |
| the organization Id with which the Access Token and subscriptions are associated |
Example Request:
curl -H 'access-token: api_app_99999999999999999999999999999999' \
'https://api2.branch.io/scheduled-exports/logs/subscription/13dbe05c-175b-11ec-9621-0242ac130002?app_id=123456789009876543'
Response Body Parameters:
Parameter | Description | Required |
---|---|---|
| a persistent id for this subscription, used to check the status, locate recent export jobs, and make modifications | YES |
| information about the report that should be generated. | n/a |
| how frequently the report is generated, and for what time period it is generated. Options: | YES |
| format in which the export data is delivered. Options: | YES |
| method by which the export data should be compressed. Options: | NO |
| data source from which data should be exported. See the Custom Export API's list of Branch Available Topics. | YES |
| fields (e.g. CSV columns) which should be exported. See the Custom Export API's list of Branch Available EO Fields. | YES |
| filter used to reduce which data points (e.g. CSV rows) which should be exported. See the Custom Export API's Cthulhu Filter Specification. | NO |
| information about where a finished report is stored and how it can be accessed | n/a |
| where the finished report is stored and how it can be accessed. Options: | YES |
| only set if | NO |
| only set if | NO |
| only set if | NO |
| only set if | NO |
Example Response:
{
"subscription_id": "13dbe05c-175b-11ec-9621-0242ac130002",
"report": {
"cadence": "hourly",
"filter": [
"eq",
"attributed",
"true"
],
"response_format": "csv",
"response_format_compression": "gz",
"report_type": "eo_install",
"report_fields": [
"id",
"timestamp",
"user_data_os",
"user_data_idfa",
"user_data_idfv",
"user_data_aaid"
],
"subscription_status": "ACTIVE"
},
"destination": {
"cloud": null,
"bucket": null,
"prefix": null,
"subscription_type": "branch",
"resource_access_id": null
}
}
Get Details on all Export Subscriptions
Endpoint: GET /scheduled-exports/logs/subscriptions?[app_id|organization_id]={id}
Returns all export subscriptions for an app or org. See what data is being exported (e.g. topic, columns, filters) and where data is exported to (e.g. email addresses, your data center, a Branch-hosted S3 bucket).
Request Headers
Header | Description |
---|---|
| your Access Token. Created on the Branch dashboard, associated with one user. Can be retrieved from the User page of the Dashboard — learn more here. |
Request query parameters
Provide one of the following two options:
Parameter | Description |
---|---|
| the app Id with which the Access Token and subscriptions are associated |
| the organization Id with which the Access Token and subscriptions are associated |
Example Request:
curl -H 'access-token: api_app_99999999999999999999999999999999' \
'https://api2.branch.io/scheduled-exports/logs/subscriptions?app_id=123456789009876543'
Response Body Parameters:
It is an array of subscriptions. See "Get details on one log export subscription" → "Response body parameters" above for details on subscriptions.
Example Request:
[
{
"subscription_id": "13dbe05c-175b-11ec-9621-0242ac130002",
"report": {
"cadence": "hourly",
"filter": [
"eq",
"attributed",
"true"
],
"response_format": "csv",
"response_format_compression": "gz",
"report_type": "eo_install",
"report_fields": [
"id",
"timestamp",
"user_data_os",
"user_data_idfa",
"user_data_idfv",
"user_data_aaid"
],
"subscription_status": "ACTIVE"
},
"destination": {
"cloud": null,
"bucket": null,
"prefix": null,
"subscription_type": "branch",
"resource_access_id": null
}
}
]
Get Details on Individual Export Job
Endpoint: GET /scheduled-exports/logs/subscription/{subscription_id}/job/{job_id}
Scheduled exports run at a regular cadence. Each individual run is considered a "job" and has a "job Id". You can get details on an individual job via this endpoint, as long as you know the subscription_id
and the job_id
. This includes where data was exported to (e.g. email addresses, your data center, a Branch-hosted S3 bucket).
If you do not know the job_id
and are instead trying to discover jobs associated with the subscription, see the next section: Get details on many export jobs
.
Request Headers
Header | Parameter |
---|---|
| your Access Token. Created on the Branch dashboard, associated with one user. Can be retrieved from the User page of the Dashboard — learn more here. |
Request URL Parameters
Parameter | Description |
---|---|
| the relevant subscription Id. |
| the relevant job Id. |
Request Query Parameters
Provide one of the following two options:
Parameter | Description |
---|---|
| the app Id with which the Access Token and subscriptions are associated |
| the organization Id with which the Access Token and subscriptions are associated |
Example Request:
curl -H 'access-token: api_app_99999999999999999999999999999999' \
'https://api2.branch.io/scheduled-exports/logs/subscription/13dbe05c-175b-11ec-9621-0242ac130002/job/185c97bb-f928-4f0a-b295-63f2a087780e?app_id=123456789009876543'
Response Body Parameters:
Parameter | Description |
---|---|
| a persistent identifier for this export job run |
| whether the job is in progress, succeeded or failed. Options: |
| the earliest date for which exported objects will be included. Format: |
| the latest date for which exported objects will be included. Format: |
| if the export job is for a subscription with |
| number of objects in the export (e.g. CSV rows). |
Example Response:
{
"job_id": "185c97bb-f928-4f0a-b295-63f2a087780e",
"status": "SUCCEEDED",
"start_date": "2021-09-16T01:00:00",
"end_date": "2021-09-16T01:59:59",
"export_url": [
"https://branch-exports-web.s3.us-west-1.amazonaws.com/v2/y%3D2021/m%3D09/d%3D16/app_id%3D123456789009876543/job_id%3D185c97bb-f928-4f0a-b295-63f2a087780e/task_id%3D0/123456789009876543-2021-09-16-eo_install-v2-7b7b72ee4e1a68a1ab57b626d3bc3701f0f39f4b976141fc5fcadf83e5ba5605-FSQEXZ-0.csv.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210916T023737Z&X-Amz-SignedHeaders=host&X-Amz-Expires=604800&X-Amz-Credential=AKIA3HUFQARV3GLL7FKD%2F20210916%2Fus-west-1%2Fs3%2Faws4_request&X-Amz-Signature=19ad618f5c8a13bdf072925f664699c522b525187a968fb33442cb4abc915680"
],
"lines_exported": 43
}
Get Details on Many Export Jobs
Endpoint: GET /scheduled-exports/logs/subscription/{subscription_id}/jobs
Scheduled exports run at a regular cadence. Each individual run is considered a "job" and has a "job Id". You can get details on all recent export jobs for the subscription. This includes where data was exported to (e.g. email addresses, your data center, a Branch-hosted S3 bucket).
Request Headers
Header | Description |
---|---|
| your Access Token. Created on the Branch dashboard, associated with one user. Can be retrieved from the User page of the Dashboard — learn more here. |
Request URL Parameters
Parameter | Description |
---|---|
| the relevant subscription Id. |
Request URL Query Parameters
Parameter | Description |
---|---|
| earliest date of export job runs to be included. Format: |
| latest date of export job runs to be included. Format: |
Updated 7 months ago