🚧

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.

👍

Try it!

Try out the Scheduled Log Exports API using your Branch data via the API reference here

Overview

Benefits of Scheduled Log Exports API

Scheduled Log Exports allow you to schedule daily or hourly exports of log-level data from Branch. The results are made available in one of two ways:

  • Data stored in Branch's AWS S3 bucket
  • Data delivered to your cloud data service (i.e. AWS S3)

API Limitations

Limitation

Details

Subscription Limit

35 Subscriptions

Prerequisites & API Access

In order to access the Scheduled Log Exports API, a user will need to have both Aggregate Data and Export access.

Providing Agencies API 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 provide them with access to the Cohort Exports.

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 Export API require an api_key and app_id query string parameter to be passed with each request. API Keys are generated on a per-user basis and are permanent.

Learn how to retrieve your API key (a.k.a. Access Token).

🚧

API Key/Access Token

In order to retrieve or reset your API Key/Access Token, you must have access to the Organizational Level of the Branch account. This functionality is not present at the App Level

API Usage

Cohort Export Request

POST https://api2.branch.io/v2/analytics
Content-Type: application/json
Host: api2.branch.io

Request Headers:

Header

Description

Required

Access-Token

Key that encapsulates the user's permission w.r.t an org. Obtained from the Branch Dashboard needed for authentication.

Yes

Content-Type

application/json

Yes

app_id

Application ID

Yes

API Usage

New Subscription with Data Stored in Branch's S3 Bucket Request

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).

POST /scheduled-exports/logs/subscribe

🚧

Duplicate Subscriptions

In order to prevent duplicate active subscriptions from 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.

Request Headers:

Header

Description

Required

Access-Token

Key that encapsulates the user's permission w.r.t an org. Obtained from the Branch Dashboard needed for authentication.

Yes

Content-Type

application/json

Yes

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"
  • "daily"

Yes

report.response_format

Format in which the export data is delivered.
Options:

  • "csv"
  • "json"
  • "parquet"

Yes

report.response_format_compression

The method by which the export data should be compressed. Options:

  • "gz"
  • "snappy"

Default: "gz"

No

report.report_type

The data source from which data should be exported. See the Custom Export API's list of Branch Available Topics.

Yes

report.report_fields

The 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

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 Request/Response:

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

POST /scheduled-exports/logs/subscribe

Request Headers:

Header

Description

Required

Access-Token

Key that encapsulates the user's permission w.r.t an org. Obtained from the Branch Dashboard needed for authentication.

Yes

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

Default: "gz"

No

report.report_type

The 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

The 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

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 Individual Export Subscription" below.

Example Request/Response:

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

For this type of subscription, you'll set destination.subscription_type = "email".

POST /scheduled-exports/logs/subscribe

Request Headers:

Header

Description

Required

Access-Token

Key that encapsulates the user's permission w.r.t an org. Obtained from the Branch Dashboard needed for authentication.

Yes

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

Yes

report.response_format

format in which the export data is delivered.
Options:

  • "csv"
  • "json"
  • "parquet"

Yes

report.response_format_compression

The method by which the export data should be compressed. Options:

  • "gz"
  • "snappy"

Defaults: "gz"

No

report.report_type

The data source from which data should be exported. See the Custom Export API's list of Branch Available Topics.

Yes

report.report_fields

The fields (e.g. CSV columns) which should be exported. See the Custom Export API's list of Branch Available EO Fields.

Yes

report.filter

The 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 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

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 Individual Log Export Subscription" below.

Example Request/Response:

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

Deactivates a single export subscription for a given Subscription Id.

DELETE /scheduled-exports/logs/subscription/{subscription_id}

Request Headers:

Header

Description

Required

Access-Token

Key that encapsulates the user's permission w.r.t an org. Obtained from the Branch Dashboard needed for authentication.

Yes

Request Query Parameters:

Parameter

Description

{subscription_id}

The relevant subscription Id.

Response Body Parameters

Parameter

Description

status

Whether the deactivate request succeeded.

description

More information about the status of the request

Example Request/Response:

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'
{
  "status": "SUCCESS",
  "description": "Subscription deactivated successfully"
}

Retrieve "external 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).

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

Request Headers:

Header

Description

Required

Access-Token

Key that encapsulates the user's permission w.r.t an org. Obtained from the Branch Dashboard needed for authentication.

Yes

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.

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 Request/Response:

curl -H 'access-token: api_app_99999999999999999999999999999999' \
  'https://api2.branch.io/scheduled-exports/logs/subscription/externalId?app_id=123456789009876543'
{"external_id":"9da763b0-175b-11ec-9621-0242ac130002"}

Get Details on Individual Export Subscription

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).

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

Request Headers:

Header

Description

Required

Access-Token

Key that encapsulates the user's permission w.r.t an org. Obtained from the Branch Dashboard needed for authentication.

Yes

Response Path 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.

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

The 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"
  • "daily"

Yes

report.response_format

The format in which the export data is delivered.
Options:

  • "csv"
  • "json"
  • "parquet"

Yes

report.response_format_compression

**The method by which the export data should be compressed. Options**:

  • "gz"
  • "snappy"

Default: "gz"

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

The fields (e.g. CSV columns) which should be exported. See the Custom Export API's list of Branch Available EO Fields.

Yes

report.filter

The 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 Request/Response:

curl -H 'access-token: api_app_99999999999999999999999999999999' \
  'https://api2.branch.io/scheduled-exports/logs/subscription/13dbe05c-175b-11ec-9621-0242ac130002?app_id=123456789009876543'
{
  "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

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).

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

Request Headers:

Header

Description

Required

Access-Token

Key that encapsulates the user's permission w.r.t an org. Obtained from the Branch Dashboard needed for authentication.

Yes

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.

Response Body Parameters

An array of subscriptions is returned, and a subscription is defined below:

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

The 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"
  • "daily"

Yes

report.response_format

The format in which the export data is delivered.
Options:

  • "csv"
  • "json"
  • "parquet"

Yes

report.response_format_compression

**The method by which the export data should be compressed. Options**:

  • "gz"
  • "snappy"

D****efault: "gz"

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

The fields (e.g. CSV columns) which should be exported. See the Custom Export API's list of Branch Available EO Fields.

Yes

report.filter

The 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 Request/Response:

curl -H 'access-token: api_app_99999999999999999999999999999999' \
  'https://api2.branch.io/scheduled-exports/logs/subscriptions?app_id=123456789009876543'
[
  {
    "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

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.

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

Request Headers:

Header

Description

Required

Access-Token

Key that encapsulates the user's permission w.r.t an org. Obtained from the Branch Dashboard needed for authentication.

Yes

Response Path 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.

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"
"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 Request/Response:

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'
{
  "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 (e.g. email addresses, your data center, a Branch-hosted S3 bucket).

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

Request Headers:

Header

Description

Required

Access-Token

Key that encapsulates the user's permission w.r.t an org. Obtained from the Branch Dashboard needed for authentication.

Yes

Response Path Parameters

Parameter

Description

{subscription_id}

The relevant subscription Id.

Request 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.

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