Scheduled Log Exports API

The Scheduled Log Exports API lets you set up a recurring export of select device-level data that runs on a daily or hourly basis.

Read the Scheduled Log Exports API overview

Get details on a single export job

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

This endpoint provides a way to get details on the particular job, as long as you know the subscription_id and the job_id. Scheduled exports run at a regular cadence. Each individual run is considered a "job" and has a "job ID".

Parameters

job_idstringpathRequired
The relevant job ID.
subscription_idstringpathRequired
A persistent ID for the specific subscription.

Returns

Export job success response. Returns 400 and 404 on failure — see the response panel for the error shape.

subscription_id*job_id*app_id*Access-Token*

curl 'https://api2.branch.io/scheduled-exports/logs/subscription/XXXX-0000-xxxx/job/XXXX-0000-xxxx?app_id=%3Capp_id%3E' \
  --request GET \
  --header 'Access-Token: <Access-Token>'

Response

Export job success response.

{
  "job_id": "XXXX-0000-xxxx",
  "status": "SUCCEEDED",
  "start_date": "2023-05-19T00:00:00.000-00:00",
  "end_date": "2023-05-20T00:00:00.000-00:00",
  "export_url": [
    "https://branch-exports-web-usw2.s3.us-west-1.amazonaws.com/v2/y%3D2021/m%3D09/d%3D16/app_id%3D{APP_ID}/job_id%3Da1b2c3d4/task_id%3D{TASK_ID}/unique-csv-file-name-here.csv.gz?X-Amz-Algorithm={AMZ_ALGORITHM}&X-Amz-Date={AMZ_DATE}&X-Amz-SignedHeaders={AMZ_SIGNED_HEADERS}&X-Amz-Expires={AMZ_EXPIRATION}&X-Amz-Credential={AMZ_CREDENTIAL}&X-Amz-Signature={AMZ_SIGNATURE}"
  ],
  "lines_exported": 43
}

Get details on a single subscription

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

This endpoint lets you retrieve the subscription status via the subscription_url provided. Make sure the subscription_status is set to ACTIVE.

Parameters

subscription_idstringpathRequired
A persistent ID for the specific subscription.

Returns

Status of aggregate export. Returns 400 and 404 on failure — see the response panel for the error shape.

subscription_id*app_id*Access-Token*

curl 'https://api2.branch.io/scheduled-exports/logs/subscription/XXXX-0000-xxxx?app_id=%3Capp_id%3E' \
  --request GET \
  --header 'Access-Token: <Access-Token>'

Response

Status of aggregate export.

{
  "subscription_id": "XXXX-0000-xxxx",
  "report": {
    "cadence": "hourly",
    "response_format": "csv",
    "response_format_compression": "gz",
    "report_type": "eo_install",
    "report_fields": [
      "name"
    ],
    "filter": [
      ""
    ],
    "subscription_status": "ACTIVE"
  },
  "destination": {
    "subscription_type": "cloud",
    "cloud": "s3",
    "bucket": "my-branch-export-bucket",
    "prefix": "my-folder",
    "resource_access_id": "arn:aws:iam::xxxxxxxxxxxx:role/role-name-here",
    "recipient_emails": [
      "example@branch.io"
    ]
  }
}

Get details on all subscriptions

GET/scheduled-exports/logs/subscriptions

Returns all export subscriptions for an app or organization. See what data is being exported (for example, topic, columns, and filters) and where data is exported to (for example, email addresses, your data center, or a Branch-hosted S3 bucket). Note: You need to provide either app_id or organization_id along with accessToken to execute this operation.

Parameters

No parameters.

Returns

Array of available subscriptions. Returns 400 and 404 on failure — see the response panel for the error shape.

app_id*Access-Token*

curl 'https://api2.branch.io/scheduled-exports/logs/subscriptions?app_id=%3Capp_id%3E' \
  --request GET \
  --header 'Access-Token: <Access-Token>'

Response

Array of available subscriptions.

[
  {
    "subscription_id": "XXXX-0000-xxxx",
    "report": {
      "cadence": "hourly",
      "response_format": "csv",
      "response_format_compression": "gz",
      "report_type": "eo_install",
      "report_fields": [
        "name"
      ],
      "filter": [
        ""
      ],
      "subscription_status": "ACTIVE"
    },
    "destination": {
      "subscription_type": "cloud",
      "cloud": "s3",
      "bucket": "my-branch-export-bucket",
      "prefix": "my-folder",
      "resource_access_id": "arn:aws:iam::xxxxxxxxxxxx:role/role-name-here",
      "recipient_emails": [
        "example@branch.io"
      ]
    }
  }
]

Get external ID

GET/scheduled-exports/logs/subscription/externalId

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 (that is, S3). Note: You need to provide either app_id or organization_id along with accessToken to execute this operation.

Parameters

No parameters.

Returns

The ID to be used in the trust relationship of the role that you create to allow Branch to access your S3 bucket. Returns 400 and 404 on failure — see the response panel for the error shape.

app_id*Access-Token*

curl 'https://api2.branch.io/scheduled-exports/logs/subscription/externalId?app_id=%3Capp_id%3E' \
  --request GET \
  --header 'Access-Token: <Access-Token>'

Response

The ID to be used in the trust relationship of the role that you create to allow Branch to access your S3 bucket.

{
  "external_id": "XXXX-0000-xxxx"
}

Create subscription

POST/scheduled-exports/logs/subscribe

Set up a new scheduled log export subscription. Supported at both the app and organization levels. The result is a subscription that specifies what data will be exported (for example, topic, columns, and filters) and where data will be exported to.

Parameters

destinationobjectRequiredExpandable
Information about where a finished report is stored and how it can be accessed.
reportobjectRequiredExpandable
Information about the report that should be generated.

Returns

Status of aggregate export. Returns 401, 404, and 500 on failure — see the response panel for the error shape.

app_id*Access-Token*

curl 'https://api2.branch.io/scheduled-exports/logs/subscribe?app_id=%3Capp_id%3E' \
  --request POST \
  --header 'Access-Token: <Access-Token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "report": {
      "cadence": "hourly",
      "response_format": "csv",
      "response_format_compression": "gz",
      "report_type": "eo_install",
      "report_fields": [
        "name"
      ]
    },
    "destination": {
      "subscription_type": "cloud",
      "cloud": "s3",
      "bucket": "my-branch-export-bucket",
      "prefix": "my-folder",
      "resource_access_id": "arn:aws:iam::xxxxxxxxxxxx:role/role-name-here"
    }
  }'

Response

Status of aggregate export.

{
  "subscription_id": "XXXX-0000-xxxx",
  "status": "PENDING",
  "description": "Generating sample report. Subscription will finish after Report is uploaded",
  "subscription_url": "https://api2.branch.io/scheduled-exports/exports/logs/subscription/{SUBSCRIPTION_ID}?app_id={APP_ID}"
}

Get details on many export jobs

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

Once your subscription is active, you can query for the exported data and download the data via the array export_url. For data accessible via API, the files are stored in Branch's S3 bucket, and you're provided a pre-signed S3 URL for exporting data. Typically, data is accessible via API for 7 days, so be sure to download your data shortly after it's generated.

Parameters

app_idstringqueryRequired
Unique identifier for the Branch app of the requested data.
end_datestringRequired
The latest date of export job runs to be included. Time zone is UTC. Format: yyyy-MM-dd'T'HH:mm:ssZ.
start_datestringRequired
The earliest date of export job runs to be included. Time zone is UTC. Format: yyyy-MM-dd'T'HH:mm:ssZ.
subscription_idstringpathRequired
ID for your subscription. Obtained from the /subscribe path.

Returns

OK—returns an array of export jobs. Returns 400 on failure — see the response panel for the error shape.

subscription_id*app_id*Access-Token*

curl 'https://api2.branch.io/scheduled-exports/logs/subscription/a1b2c3d4/jobs?app_id=123456789012345678' \
  --request POST \
  --header 'Access-Token: <Access-Token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "start_date": "2021-08-16T02:00:00",
    "end_date": "2021-08-16T02:59:59"
  }'

Response

OK—returns an array of export jobs.

[
  {
    "job_id": "XXXX-0000-xxxx",
    "status": "SUCCEEDED",
    "start_date": "2023-05-19T00:00:00.000-00:00",
    "end_date": "2023-05-20T00:00:00.000-00:00",
    "export_url": [
      "https://branch-exports-web-usw2.s3.us-west-1.amazonaws.com/v2/y%3D2021/m%3D09/d%3D16/app_id%3D{APP_ID}/job_id%3Da1b2c3d4/task_id%3D{TASK_ID}/unique-csv-file-name-here.csv.gz?X-Amz-Algorithm={AMZ_ALGORITHM}&X-Amz-Date={AMZ_DATE}&X-Amz-SignedHeaders={AMZ_SIGNED_HEADERS}&X-Amz-Expires={AMZ_EXPIRATION}&X-Amz-Credential={AMZ_CREDENTIAL}&X-Amz-Signature={AMZ_SIGNATURE}"
    ],
    "lines_exported": 43
  }
]

Deactivate subscription

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

Deactivates a single export subscription for a given subscription ID.

Parameters

subscription_idstringpathRequired
A persistent ID for the specific subscription.

Returns

Status of aggregate export. Returns 400 and 404 on failure — see the response panel for the error shape.

subscription_id*app_id*Access-Token*

curl 'https://api2.branch.io/scheduled-exports/logs/subscription/XXXX-0000-xxxx?app_id=%3Capp_id%3E' \
  --request DELETE \
  --header 'Access-Token: <Access-Token>'

Response

Status of aggregate export.

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