Scheduled Log Exports API Reference

Full reference for the Schedule Log Exports API

🚧

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.

Updated 20 days ago


Recommended Next Steps

Scheduled Log Exports API Guide

Scheduled Log Exports API Reference


Full reference for the Schedule Log Exports API

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.


Filters