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 programatically.
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
Prerequisites
In order to use the Cohort API, you first need to:
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 Exportaccess 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:
Under Access Level, check the Export box.
Under Permissions, check the Aggregate Data box.
Optional: add data filters
Under Data Filters, toggle any necessary data filters on/blue. Exported data will be filtered accordingly.
Click Save.
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
Calls to the Cohort API require an api_key query string parameter to be passed with each request. API keys are generated on a per-user basis and are permanent.
NOTE: 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.
Usage
Export Cohort Analytics
Request Info
Export Request
POST https://api2.branch.io/v2/analytics
Content-Type: application/json
Host: api2.branch.io
HTTP
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_idorapp_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.
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
Unique identifier used to retrieve job status and data. This is used in the "Get Export Download Status" request.