Cohort API Overview

Overview

Cohort Analytics is a powerful tool that helps you not only understand the full ROI of your campaigns, but also helps you guide future investment decisions and consumer targeting.

With the Branch Cohort API, you can access Cohort Analytics data programmatically.

Benefits of Cohort API

Cohorts Analytics data allows you to analyze your cross-channel, cross-platform performance by either acquisition date (app install only) or re-engagement date (web and app sessions), to see how those users performed over time.

Limitations

Limitation	Details
Max Number of Records Returned	50,000 We may define dynamic record limits based on `app_id` or `organization_id`.
Export Window	Rolling 2 year window.
Max Number of Dimensions	11 dimensions.
Max Number of Measures	5 measures.
Max Number of Days Queried	90 days.
Rate Limits	2 requests per second. 5 requests per minute. 150 requests per hour.

Getting Started

Before you begin

In order to use the Cohort API, you first need to:

Create a Branch Dashboard.
Implement the appropriate Branch SDK into your mobile app (iOS | Android).
Make sure you have the appropriate permissions set on your user account. See the "Access" section for more.

Access

General Access

To access the Async Aggregate 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 provide them with access to the Cohort API.

To provide an agency team member with access to the Cohort API:

In the left-hand navigation, under Setup & Testing, click on Account Settings.
On the Account Settings page, click on the Agencies tab.
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.
In the Edit Agency Team Member modal:
1. Under Access Level, check the Export box.
2. Under Permissions, check the Aggregate Data box.
Optional: add data filters
1. Under Data Filters, toggle any necessary data filters on/blue. Exported data will be filtered accordingly.
Click Save.

1246

Agency-Tagged Data
If you do not enable the Only Show Agency-Tagged Data data filter, the Agency Team Member will be able to export aggregate data associated with all of your campaigns, regardless if they are associated with them or not.

Authentication

For calls to the Cohort API, you will need your Access Token.

Legacy Branch

New Branch

To retrieve your credentials in the legacy Branch experience:

Navigate to the Account → Settings → User tab.
If you have not yet generated an Access Token, select the Generate token button.
Use the copy icon to copy your Access Token.

To retrieve your credentials in the new Branch experience:

Navigate to the Configuration → Security & Access → Credentials tab.
If you have not yet generated an Access Token, select the Generate token button.
Use the copy icon to copy your Access Token.

Visit our guide to learn more about managing your Branch credentials.

Usage

Export Cohort Analytics

Request Info

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 with regards to an organization. Obtained from the Branch Dashboard. Needed for authentication.	Yes
`accept`	application/json	Recommended
`content-type`	application/json	Recommended

Request Query Parameters

Parameter	Description	Required
`organization_id` or `app_id`	Unique identifier for the organization of requested data.	Yes
`limit`	The maximum number of results to return. Default: 100 Min: 1 Max: 50000 (unless a higher limit is provisioned)	No
`format`	Format of the returned data. Defaults to CSV.	No

Request Body Parameters

Parameter	Type	Description	Required
`start_date`	Date	The start of the interval time range represented as an ISO-8601 complete date.	Yes
`end_date`	Date	The end of the interval time range represented as an ISO-8601 complete date.	Yes
`dimensions`	Array of Strings	An array representing dimension(s) to group by. See the "Dimensions" section for a complete list. Limit is 11.	No
`data_source`	String	A string value representing the cohort type. Can be either: - `"install_cohort"` - `"reengagement_cohort"`	Yes
`filters`	Array of Strings	Keys are same as dimensions. Values are an array of values to match for the dimension. An object defining filters to match or disallow certain values.	No
`ordered`	String	Order of response, based on `ordered_by` value. - `"ascending"` - `"descending"`Default: `"descending"`	No
`ordered_by`	String	The dimension name used for sorting. See the "Dimensions" section for a complete list.	No
`measures`	String	The cohort measures names to return. Limit is 3. See the "Measures" section for a complete list.	Yes
`granularity_band_count`	Integer	Number of time units since the cohort event to return to the user.	Yes
`cumalative`	Boolean	If `true`, sum across bands so that a given band value is the sum of all preceding values, plus the band value. Default: `false`	No
`per_user`	Boolean	If `true`, divide each band value by the user count. Default: `false`	No
`granularity`	String	The time granularity that each band value will represent. Default: `"day"`	No
`enable_install_recalculation`	Boolean	If `true`, then Branch will de-dupe unattributed installs caused by duplicate events from non-opt-in users coming from paid ads. This is related to iOS 14.5 privacy changes.	No

Response Info

Response Body Parameters

Parameter	Description
`job_id`