🚧
Alpha API
This API is in alpha and is available to enterprise customers only. If you would like to use this feature, please reach out to your account executive.

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
`access-token`	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
`report`	information about the report that should be generated.	n/a
`report.cadence`	how frequently the report is generated, and for what time period it is generated. Options: `hourly` or `daily`.	YES
`report.response_format`	format in which the export data is delivered. Options: `csv`, `json`, `parquet`.	YES
`report.response_format_compression`	method by which the export data should be compressed. Options: `gz`, `snappy`. Defaults to `gz` if not specified.	NO
`report.report_type`	data source from which data should be exported. See the Custom Export API's list of Branch Available Topics.	YES
`report.report_fields`	fields (e.g. CSV columns) which should be exported. See the Custom Export API's list of Branch Available EO Fields.	YES
`report.filter`	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
`destination`	information about where a finished report is stored and how it can be accessed	n/a
`destination.subscription_type`	should be set to `branch` if you want data stored in Branch's S3 bucket, and accessible via API	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
`subscription_id`	a persistent id for this subscription, used to check the status, locate recent export jobs, and make modifications
`status`	if `PENDING`, Branch is still working on an initial export to test out this subscription. If `ACTIVE` then the subscription was set up successfully. If `FAILED` then the test export was unsuccessful.
`description`	more information about the subscription's status.
`subscription_url`	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
`access-token`	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
`report`	information about the report that should be generated.	n/a
`report.cadence`	how frequently the report is generated, and for what time period it is generated. Options: `hourly` or `daily`.	YES
`report.response_format`	format in which the export data is delivered. Options: `csv`, `json`, `parquet`.	YES
`report.response_format_compression`	method by which the export data should be compressed. Options: `gz`, `snappy`. Defaults to `gz` if not specified.	NO
`report.report_type`	data source from which data should be exported. See the Custom Export API's list of Branch Available Topics.	YES
`report.report_fields`	fields (e.g. CSV columns) which should be exported. See the Custom Export API's list of Branch Available EO Fields.	YES
`report.filter`	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
`destination`	information about where a finished report is stored and how it can be accessed	N/A
`destination.subscription_type`	should be set to `"cloud"` if you want the data exported to your own cloud.	YES
`destination.cloud`: should be set to `"s3"`	In the future we may support other options beyond AWS S3.	YES
`destination.resource_access_id`	the ARN for the AWS Role you are using for Branch exports. E.g. `arn:aws:iam::xxxxxxxxxxxx:role/Branch-Export-Upload-*`.	YES
`destination.bucket`	the AWS bucket you are using for Branch exports. Do not include `s3://` or any other prefix or suffix.	YES
`destination.prefix`	the prefix or folder you are using for Branch exports. E.g. if you are exporting to `s3://my-branch-export-bucket/my-folder/`, then this value should be `my-folder`.	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
`subscription_id`	a persistent id for this subscription, used to check the status, locate recent export jobs, and make modifications
`status`	if `PENDING`, Branch is still working on an initial export to test out this subscription. If `ACTIVE` then the subscription was set up successfully. If `FAILED` then the test export was unsuccessful.
`description`	more information about the subscription's status.
`subscription_url`	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"
}

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
`access-token`	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
`{subscription_id}`	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
`status`	whether the deactivate request succeeded
`description`	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
`access-token`	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
`app_id`	the app Id with which the Access Token and subscriptions are associated
`organization_id`	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
`external_id`	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
`access-token`	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
`{subscription_id}`	the relevant subscription Id.

Request Query Parameters
Provide one of the following two options:

Parameter	Description
`app_id`	the app Id with which the Access Token and subscriptions are associated
`organization_id`	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
`subscription_id`	a persistent id for this subscription, used to check the status, locate recent export jobs, and make modifications	YES
`report`	information about the report that should be generated.	n/a
`report.cadence`	how frequently the report is generated, and for what time period it is generated. Options: `hourly` or `daily`.	YES
`report.response_format`	format in which the export data is delivered. Options: `csv`, `json`, `parquet`.	YES
`report.response_format_compression`	method by which the export data should be compressed. Options: `gz`, `snappy`. Defaults to `gz` if not specified.	NO
`report.report_type`	data source from which data should be exported. See the Custom Export API's list of Branch Available Topics.	YES
`report.report_fields`	fields (e.g. CSV columns) which should be exported. See the Custom Export API's list of Branch Available EO Fields.	YES
`report.filter`	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
`destination`	information about where a finished report is stored and how it can be accessed	n/a
`destination.subscription_type`	where the finished report is stored and how it can be accessed. Options: `branch`, `cloud`, `email`. `branch`: data is stored in Branch's S3 bucket and can be accessed via API. See "Get details on many export jobs" below. `cloud`: data is stored in your own cloud data service (i.e. AWS S3). `email` is coming soon.	YES
`destination.cloud`	only set if `subscription_type` is set to `cloud`. Specifies which cloud (e.g. `s3`).	NO
`destination.resource_access_id`	only set if `subscription_type` is set to `cloud`. The ARN for the AWS Role you are using for Branch exports. E.g. `arn:aws:iam::xxxxxxxxxxxx:role/Branch-Export-Upload-*`.	NO
`destination.bucket`	only set if `subscription_type` is set to `cloud`. The AWS bucket you are using for Branch exports.	NO
`destination.prefix`	only set if `subscription_type` is set to `cloud`. The prefix or folder you are using for Branch exports. E.g. if you are exporting to `s3://my-branch-export-bucket/my-folder/`, then this value will be `my-folder`.	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
`access-token`	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
`app_id`	the app Id with which the Access Token and subscriptions are associated
`organization_id`	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
`access-token`	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
`{subscription_id}`	the relevant subscription Id.
`{job_id}`	the relevant job Id.

Request Query Parameters
Provide one of the following two options:

Parameter	Description
`app_id`	the app Id with which the Access Token and subscriptions are associated
`organization_id`	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
`job_id`	a persistent identifier for this export job run
`status`	whether the job is in progress, succeeded or failed. Options: `PENDING_GENERATION`, `PENDING_UPLOAD`, `RUNNING`, `SUCCEEDED` and `FAILED`
`start_date`	the earliest date for which exported objects will be included. Format: `yyyy-MM-dd'T'HH:mm:ssZ`. Timezone is UTC.
`end_date`	the latest date for which exported objects will be included. Format: `yyyy-MM-dd'T'HH:mm:ssZ`. Timezone is UTC. (Note: this includes data through the final millisecond. So if `end_date` is `2021-09-30T19:59:59`, this export job run will include data through the final millisecond i.e. `2021-09-30T19:59:59.999`)
`export_url`	if the export job is for a subscription with `destination.subscription_type` set to `branch`, then this will be an array of pre-signed S3 URLs for export files that you can then download.
`lines_exported`	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
`access-token`	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
`{subscription_id}`	the relevant subscription Id.

Request URL Query Parameters

Parameter	Description
`start_date`	earliest date of export job runs to be included. Format: `yyyy-MM-dd'T'HH:mm:ss.SSSZ`. Timezone is UTC.
`end_date`	latest date of export job runs to be included. Format: `yyyy-MM-dd'T'HH:mm:ss.SSSZ`. Timezone is UTC.

Developers Hub

Scheduled Log Exports API Reference

🚧
Alpha API

Set Up a New Subscription

New Subscription with Data Stored in Branch's S3 Bucket

New Subscription with Data Stored in your own Cloud

Deactivate a Subscription

Retrieve "external Id"

Get Details on Individual Export Subscription

Get Details on all Export Subscriptions

Get Details on Individual Export Job

Get Details on Many Export Jobs

Recommended Next Steps

Scheduled Log Exports API Reference

Suggested Edits are limited on API Reference Pages

🚧Alpha API

Set Up a New Subscription

New Subscription with Data Stored in Branch's S3 Bucket

New Subscription with Data Stored in your own Cloud

Deactivate a Subscription

Retrieve "external Id"

Get Details on Individual Export Subscription

Get Details on all Export Subscriptions

Get Details on Individual Export Job

Get Details on Many Export Jobs

Recommended Next Steps

Filters

🚧
Alpha API