Overview

Branch's Scheduled Log Exports API lets you schedule daily or hourly exports of log-level data from Branch.

These results are made available to you in one of three ways:

1. The data is stored in Branch's AWS S3 bucket
2. The data is delivered to your own cloud storage account (AWS or GCP)
3. The data is delivered to you via email

You can stay on top of monitoring the data by creating a subscription to a particular feed. A subscription is a single report (which includes information such as data source, fields, and filters) that is set up to be exported over and over at a regular cadence.

A job represents one time that the report was run and data was exported. The result is one or more files with exported data. Depending on the cadence, a job results in exporting data for either one hour or one day.

Access

Access to the Scheduled Log Exports API requires our Advanced Data Feeds add-on.

The Advanced Data Feeds add-on also includes access to:

• The Cross-Events Export API.
• The Unified Analytics Export API.
• Data integrations for exports.
• Webhook functionality.

Learn more on our pricing page.

Benefits

With the Scheduled Log Exports API, your log-level data can be funneled to a number of different places, and new data is made available to you on a daily cadence.

Use Cases

• Automate Branch log-level data retrieval based on a schedule (hourly or daily), selecting your own data fields and filters.
• Set up notifications on sudden day-over-day increases/decreases in attributed installs.
• Export your data directly to your cloud account. There is no need to manually request exports - instead, your data goes directly to your cloud storage where you can access it at any time.
• Set up regular exports to agencies with the ability to hide certain data from partners to protect privacy, increasing your control over your data.
• Set up recurring emails with custom reports to share agency-attributed installs with your agency via email. Also share ad network postback records with your ad network.

Limits

Try It!

Try out the Scheduled Log Exports API in your browser, using your Branch data:

Get External ID (only relevant if you are storing Branch data in your own cloud)

Create New Subscription

Deactivate Subscription

Get Details on Single Subscription

Get Details on All Subscriptions

Get Details on Single Export Job

Get Details on Many Export Jobs

Getting Started

Prerequisites

In order to use the Scheduled Log Exports API, you first need to:

1. Create a Branch Dashboard.
2. Make sure you have the appropriate permissions set on your account. See the "Access" section for more.

Cloud Storage

If you want to store your Scheduled Log Exports API data in your own cloud storage account (AWS or GCP), you will need to:

1. Retrieve your external ID from Branch by using this API's /scheduled-exports/logs/subscription/externalId endpoint.
2. Follow our cloud set up guide to properly configure your AWS or GCP account to receive data from Branch.
3. Use this API's /scheduled-exports/logs/subscribe endpoint to create a new subscription that points the data to your cloud storage account.

Access

Access to the Scheduled Log Exports API requires our Advanced Data Feeds add-on.

Learn more on our pricing page.

General Access

To access the Scheduled Log Exports API, a user must have both Aggregate Data and Export access enabled on their account.

Agency Access

If you work with an agency that runs your advertising campaigns and want to give them access to export the subsequent data, you can give them Export and Aggregate Data access.

To provide an agency team member with access to the Scheduled Log Exports:

1. In the left-hand navigation, under Setup & Testing, click on Account Settings.
2. On the Account Settings page, click on the Agencies tab.
3. Expand the agency in question, find the agency team member you want to give access to, hover on the button in the Actions column, and click Edit.
4. In the Edit Agency Team Member modal:
   1. Under Access Level, check the Export box.
   2. Under Permissions, check the Aggregate Data box.
5. Optional: add data filters
   1. Under Data Filters, toggle any necessary data filters on/blue. Exported data will be filtered accordingly.
6. Click Save.

Authentication

Calls to the Scheduled Log Exports API require an api_key and app_id query string parameters to be passed with each request.

Important notes about your API key:

• API keys are generated on a per-user basis and are permanent.
• In order to retrieve or reset your API key/access token, you must have Organizational Level access to the Branch account. This functionality is not present at the App Level.
• If the api_key being used is deleted or permissions are removed, the scheduled export will no longer work and will be deactivated.
• You must use the same api_key that was used to create the schedule originally in order to retrieve information regarding the subscription and the exports generated.

Learn how to retrieve your API key (also known as access_token) in our guide.

Usage

Get External ID

Branch provides a unique external ID for your Branch account.

This external ID can be used when setting up data to be exported to your own cloud service.

Your external ID is not relevant if you are accessing data via Branch's cloud or email.

Request Info

Endpoint

GET /scheduled-exports/logs/subscription/externalId?{app_id|organization_id}={id}

Request Headers

Request Query Parameters

Provide one of the following two options:

Response Info

Response Body Parameters

Example Request & Response

# Include either `app_id` or `organization_id` in request query

curl -H 'access-token: api_app_99999999999999999999999999999999' \
  'https://api2.branch.io/scheduled-exports/logs/subscription/externalId?app_id=123456789009876543'

{"external_id":"111111bbbb-bbb111-1b1b1b1-1111-bbb"}

Create New Subscription

This type of request sets up a new scheduled log export subscription. This is supported at both the app and org level.

The result of this request is a subscription that specifies what data will be exported and where that data will be exported to.

🚧

Duplicate Subscriptions

In order to prevent duplicate active subscriptions from being created accidentally, Branch will throw an error if you attempt to create a subscription that exactly matches an existing subscription.

This is based on the following values:

• subscription_type
• report_type
• app_id or organization_id
• fields
• filter
• cadence

However, simply re-ordering the values in fields is enough to bypass this check and create a new subscription.

Request Info

Endpoint

POST /scheduled-exports/logs/subscribe

Request Headers

Request Body Parameters

Response Info

Response Body Parameters

Examples

Example Requests

The examples below demonstrate how to create a new subscription and make your data accessible in one of three ways: Branch's S3 storage, your own cloud storage, or a daily email.

#  Example Request: Store Data in Your Own Cloud

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'

#  Example Request: Store Data in Branch's S3 Bucket

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'

# Example Request: Receive a Daily Email

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'

Example Generic Response

{
  "subscription_id": "0000aaaa-00-0a0a-0000",
  "status": "PENDING",
  "description": "Generating sample report. Subscription will finish after Report is uploaded",
  "subscription_url": "https://api2.branch.io/scheduled-exports/exports/logs/subscription/0000aaaa-00-0a0a-0000?app_id=123456789009876543"
}

Deactivate Subscription

Request Info

Endpoint

DELETE /scheduled-exports/logs/subscription/{subscription_id}?{app_id|organization_id}={id}

Request Headers

Request Query Parameters

Response Info

Response Body Parameters

Example Request & Response

# Include either `app_id` or `organization_id` in request query

curl -X DELETE -H 'access-token: api_app_99999999999999999999999999999999' \
  'https://api2.branch.io/scheduled-exports/logs/subscription/0000aaaa-00-0a0a-0000?app_id=123456789009876543'

{
  "status": "SUCCESS",
  "description": "Subscription deactivated successfully"
}

Get Details on Single Subscription

Returns a single export subscription for a given subscription ID.

See what data is being exported and where data is exported to (Branch's cloud, your own cloud, or email).

Request Info

Endpoint

GET /scheduled-exports/logs/subscription/{subscription_id}?{app_id|organization_id}={id}

Request Headers

Request Query Parameters

Response Info

Response Body Parameters

Example Request & Response

# Include either `app_id` or `organization_id` in request query

curl -H 'access-token: api_app_99999999999999999999999999999999' \
  'https://api2.branch.io/scheduled-exports/logs/subscription/0000aaaa-00-0a0a-0000?app_id=123456789009876543'

{
  "subscription_id": "0000aaaa-00-0a0a-0000",
  "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 Subscriptions

Returns all export subscriptions for a given app or organization ID.

See what data is being exported and where data is exported to (Branch's cloud, your own cloud, or email).

Request Info

Endpoint

GET /scheduled-exports/logs/subscriptions?[app_id|organization_id]={id}

Request Headers

Request Query Parameters

Provide one of the following two options:

Response Info

Response Body Parameters

An array of subscriptions is returned.

For each unique subscription, the following fields are returned:

Example Request & Response

curl -H 'access-token: api_app_99999999999999999999999999999999' \
  'https://api2.branch.io/scheduled-exports/logs/subscriptions?app_id=123456789009876543'

[
  {
    "subscription_id": "0000aaaa-00-0a0a-0000",
    "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
    }
  },
	{
    "subscription_id": "222cc2-ccc-22c-2222",
    "report": {
      "cadence": "daily",
      "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": "s3",
      "bucket": "my-branch-export-bucket",
      "prefix": "my-folder",
      "subscription_type": "cloud",
      "resource_access_id": "arn:aws:iam::xxxxxxxxxxxx:role/Branch-Export-Upload-tbd"
    }
  }
]

Get Details on Single Export Job

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 (Branch's cloud, your own cloud, or email).

If you do not know the job_id and are instead trying to discover jobs associated with a particular subscription, see the "Get Details on Many Export Jobs" section.

Request Info

Endpoint

GET /scheduled-exports/logs/subscription/{subscription_id}/job/{job_id}

Request Headers

Response Path Parameters

Request Query Parameters

Provide one of the following two options:

Response Info

Response Body Parameters

Example Request & Response

curl -H 'access-token: api_app_99999999999999999999999999999999' \
  'https://api2.branch.io/scheduled-exports/logs/subscription/0000aaaa-00-0a0a-0000/job/185c97bb-f928-4f0a-b295-63f2a087780e?app_id=123456789009876543'

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

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 (Branch's cloud, your own cloud, or email).

Request Info

Endpoint

GET /scheduled-exports/logs/subscription/{subscription_id}/jobs

Request Headers

Request Path Parameters

Request Query Parameters

Response Body Parameters

An array of jobs is returned.

For each unique job, the following fields are returned:

Example Request & Response

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' \
-H 'access-token: api_app_99999999999999999999999999999999' -d '{
"start_date": "2021-08-16T02:00:00"
"end_date": "2021-08-16T02:59:59"
}'https://api2.branch.io/scheduled-exports/logs/subscription/13dbe05c-175b-11ec-9621-0242ac130002?app_id=123456789009876543'

{
  "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-xxxxxxxx-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%xxxxxxxx%2Fus-west-1%2Fs3%2Faws4_request&X-Amz-Signature=xxxxxxxxxxxxxxxxxx"
  ],
  "job_id": "225c97bb-f348-3c0a-d545-88c2b093710f",
  "status": "SUCCEEDED",
  "start_date": "2021-08-16T02:00:00",
  "end_date": "2021-08-16T02:59:59",
  "export_url": [
    "https://branch-exports-web.s3.us-west-1.amazonaws.com/v2/y%4D2021/m%4D09/d%4D16/app_id%4D123456789009876543/job_id%4D185c97bb-f928-4f0a-c295-63f2a087780e/task_id%4D0/223456789009876543-2021-09-16-eo_install-v2-xxxxxxxx-FSQEXZ-2.csv.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210916T023737Z&X-Amz-SignedHeaders=host&X-Amz-Expires=604800&X-Amz-Credential=AKIA3HUFQARV3GLL7FKD%xxxxxxxx%2Fus-west-1%2Fs3%2Faws4_request&X-Amz-Signature=xxxxxxxxxxxxxxxxxx"
  ],  
  "lines_exported": 86
}

Appendix

Testing and Best Practices

Test Export and Cadence

1. Set up the subscription
   1. Ensure that report.subscription_status field is set to ACTIVE
   2. Branch recommends setting report.cadence to hourly so you can validate the export sooner
2. Wait for a test export run to complete and confirm the data looks as expected

Subscription Status Pending

If you check the report.subscription_status and it is in the PENDING state, wait a few minutes and try again. You should see it update to ACTIVE.

Querying Exported Data

Once the value of report.subscription_status is ACTIVE, Branch recommends searching through a full day's worth of data initially (set via the start_date and end_date parameters), then narrowing down after that if you plan to export data one hour at a time.

Available Topics

Available Fields

Cthulhu Filter Specification

Cthulhu is a prefix notation syntax written in JSON for specifying filters on records (usually column-based records).

Purpose
Easily parses into an abstract syntax tree.

Glossary
any - any valid json basic value (number, string)
... - previous item in a list can repeat as many times as necessary

Additional Examples