Cohort API Overview

  • Updated on Jan 29, 2026
  • Published on Mar 20, 2025
Prev Next

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

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

  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.

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.

To retrieve your credentials in the legacy Branch experience:

  1. Navigate to the Account → Settings → User tab.

  2. If you have not yet generated an Access Token, select the Generate token button.

  3. Use the copy icon to copy your Access Token.

To retrieve your credentials in the new Branch experience:

  1. Navigate to the Configuration → Security & Access → Credentials tab.

  2. If you have not yet generated an Access Token, select the Generate token button.

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

Unique identifier used to retrieve job status and data. This is used in the "Get Export Download Status" request.

code

The HTTP response code.

status_url

The URL of the export request.

error_message

Error message. Only present if the query failed.

Example Request & Response

curl -X POST 'https://api2.branch.io/v2/analytics?app_id=xxxxxxxxxxx&limit=50000&format=json' -H 'Access-Token:api_app_xxxxxxxxxxxxxxxxxxxxxxxxx' -H 'content-type:application/json' -d '{
                    "start_date": "2024-05-30",
                    "end_date": "2024-05-31",
                    "dimensions": ["install_activity_touch_data_tilde_campaign"],
                    "data_source": "install_cohort",
                    "filters": {
                    "install_activity_touch_data_tilde_campaign": ["A4G"]
                    },
                    "ordered": "descending",
                    "ordered_by": "install_activity_touch_data_tilde_campaign",
                    "measures": ["OPEN"],
                    "granularity_band_count": 7,
                    "cumulative": false,
                    "per_user": false,
                    "granularity": "day",
                    "enable_intall_recalculation": true
                    }'
{
                    "code" : 200,
                    "job_id" : "7636f4ab-34d1-47d1-a9c9-xxxxxxxx",
                    "status_url" : "https://api2.branch.io/v2/analytics/xxxxxxxxx"
                    }

Get Export Download Status

GET /v2/analytics/<job_id>
        Host: api2.branch.io

Request Info

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 Path Parameters

Parameter

Description

Required

job_id

The unique identifier for a job.

Yes

Request Query Parameters

Parameter

Description

Required

organization_id or app_id

Unique identifier for the organization of requested data.

Yes

Response Info

Response Body Parameters

Parameter

Description

code

HTTP response code representing the outcome of the status request.

NOTE: a 1xx code denotes a QUEUED or RUNNING status.

status

Status of the query.

Possible status values:
QUEUED
RUNNING
FINISHED
ERROR

response_url

The AWS S3 URL for downloading the response data.

error_message

Error message. Only present if the query failed.

Example Request & Response

curl 'https://api2.branch.io/v2/analytics/<job_id>?organization_id=<organization_id>' -H 'Access-Token:<branch_access_token>'
{
                    "code" : 200,
                    "status" : "FINISHED",
                    "response_url" : "https://branch-exports.s3.amazonaws.com/partner-query/2024-05-30-2024-05-31-install_cohort-day-7636f4ab-34d1-47d1-a9c9-7cbe364953ec-xxxxxxxxxxx.json?Signature=D0zi5Jkhl073ixxxxxxxxxxxxAccessKeyId=xxxxxxxxxxxxx&Expires=1655145468"
                    }

Appendix

Filters

Filters can be combined using the AND keyword at the top level.

Each dimension can have multiple or filters e.g. { user_data_os": ["IOS", "ANDROID"] }.

Dimensions

Install Cohort

{
        "install_activity_attributed": "attributed",
        "install_activity_event_name": "event name",
        "install_activity_touch_type": "type",
        "install_activity_touch_data_tilde_campaign_id": "campaign id",
        "install_activity_touch_data_tilde_campaign": "campaign",
        "install_activity_touch_data_tilde_channel": "channel",
        "install_activity_touch_data_tilde_feature": "feature",
        "install_activity_touch_data_tilde_stage": "stage",
        "install_activity_touch_data_tilde_tags": "tags",
        "install_activity_touch_data_tilde_advertising_partner_name": "ad partner",
        "install_activity_touch_data_dollar_3p": "ad partner (3p)",
        "install_activity_touch_data_tilde_secondary_publisher": "secondary publisher",
        "install_activity_touch_data_tilde_creative_name": "creative name",
        "install_activity_touch_data_tilde_ad_id": "ad id",
        "install_activity_touch_data_tilde_ad_set_id": "ad set id",
        "install_activity_touch_data_tilde_ad_set_name": "ad set name",
        "install_activity_touch_data_tilde_ad_name": "ad name",
        "install_activity_touch_data_tilde_keyword": "keyword",
        "install_activity_touch_data_tilde_journey_name": "journey name",
        "install_activity_touch_data_tilde_view_name": "view name",
        "install_activity_touch_data_plus_referring_domain": "referring domain",
        "install_activity_touch_data_plus_via_features": "Branch feature",
        "install_activity_touch_data_plus_web_format": "web format",
        "install_activity_data_os": "os",
        "install_activity_data_environment": "environment",
        "install_activity_data_platform": "platform",
        "install_activity_data_country_code": "country",
        "install_activity_data_has_app": "has app",
        "install_activity_data_has_clicked_email": "has clicked email",
        "install_activity_data_has_clicked_ad": "has clicked ad",
        "install_activity_timezone_adjusted_day": "date",
        "install_activity_touch_data_tilde_placement": "placement",
        "install_activity_data_device_type": "device type",
        "install_activity_touch_data_tilde_sub_site_name": "sub site name",
        "install_activity_data_brand": "brand",
        "install_activity_data_geo_country_en": "geo country",
        "install_activity_data_model": "model",
        "install_activity_data_geo_region_en": "region",
        "install_activity_touch_data_tilde_customer_secondary_publisher": "customer secondary publisher",
        "install_activity_touch_data_tilde_customer_placement": "customer placement",
        "install_activity_touch_data_tilde_customer_sub_site_name": "customer sub site name",
        "install_activity_touch_data_tilde_customer_campaign": "customer campaign",
        "install_activity_touch_data_tilde_customer_ad_set_name": "customer ad set name",
        "install_activity_touch_data_tilde_customer_ad_name": "customer ad name",
        "install_activity_touch_data_tilde_customer_keyword": "customer keyword",
        "install_activity_touch_data_tilde_agency_id": "agency id",
        "install_activity_touch_data_tilde_agency": "agency name",
        "customer_event_alias": "customer event alias"
        }

Reengagement Cohort

{
        "reengagement_activity_attributed": "attributed",
        "reengagement_activity_event_name": "event name",
        "reengagement_activity_touch_type": "type",
        "reengagement_activity_touch_data_tilde_campaign_id", "campaign id",
        "reengagement_activity_touch_data_tilde_campaign": "campaign",
        "reengagement_activity_touch_data_tilde_channel": "channel",
        "reengagement_activity_touch_data_tilde_feature": "feature",
        "reengagement_activity_touch_data_tilde_stage": "stage",
        "reengagement_activity_touch_data_tilde_tags": "tags",
        "reengagement_activity_touch_data_tilde_advertising_partner_name": "ad partner",
        "reengagement_activity_touch_data_dollar_3p": "ad partner (3p)",
        "reengagement_activity_touch_data_tilde_secondary_publisher": "secondary publisher",
        "reengagement_activity_touch_data_tilde_creative_name": "creative name",
        "reengagement_activity_touch_data_tilde_ad_id": "ad id",
        "reengagement_activity_touch_data_tilde_ad_set_id": "ad set id",
        "reengagement_activity_touch_data_tilde_ad_set_name": "ad set name",
        "reengagement_activity_touch_data_tilde_ad_name": "ad name",
        "reengagement_activity_touch_data_tilde_keyword": "keyword",
        "reengagement_activity_touch_data_tilde_journey_name": "journey name",
        "reengagement_activity_touch_data_tilde_view_name": "view name",
        "reengagement_activity_touch_data_plus_referring_domain": "referring domain",
        "reengagement_activity_touch_data_plus_via_features": "Branch feature",
        "reengagement_activity_touch_data_plus_web_format": "web format",
        "reengagement_activity_data_os": "os",
        "reengagement_activity_data_environment": "environment",
        "reengagement_activity_data_platform": "platform",
        "reengagement_activity_data_country_code": "country",
        "reengagement_activity_data_has_app": "has app",
        "reengagement_activity_data_has_clicked_email": "has clicked email",
        "reengagement_activity_data_has_clicked_ad": "has clicked ad",
        "reengagement_activity_timezone_adjusted_day": "date",
        "reengagement_activity_touch_data_tilde_placement": "placement",
        "reengagement_activity_data_device_type": "device type",
        "reengagement_activity_touch_data_tilde_sub_site_name": "sub site name",
        "reengagement_activity_data_brand": "brand",
        "reengagement_activity_data_geo_country_en": "geo country",
        "reengagement_activity_data_model": "model",
        "reengagement_activity_data_geo_region_en": "region",
        "reengagement_activity_touch_data_tilde_customer_secondary_publisher": "customer secondary publisher",
        "reengagement_activity_touch_data_tilde_customer_placement": "customer placement",
        "reengagement_activity_touch_data_tilde_customer_sub_site_name": "customer sub site name",
        "reengagement_activity_touch_data_tilde_customer_campaign": "customer campaign",
        "reengagement_activity_touch_data_tilde_customer_ad_set_name": "customer ad set name",
        "reengagement_activity_touch_data_tilde_customer_ad_name": "customer ad name",
        "reengagement_activity_touch_data_tilde_customer_keyword": "customer keyword",
        "reengagement_activity_touch_data_tilde_agency_id": "agency id",
        "reengagement_activity_touch_data_tilde_agency": "agency name",
        "customer_event_alias": "customer event alias"
        }

User

{
        "user_data_platform": "platform (conversion event)",
        "user_data_environment": "environment (conversion event)",
        "user_data_geo_country_code": "country (conversion event)",
        "user_data_os": "os (conversion event)",
        "user_data_has_app": "has app (conversion event)",
        "user_data_standard_events_completed": "standard events completed (conversion event)",
        "user_data_custom_events_completed": "custom events completed (conversion event)",
        "user_data_has_clicked_ad": "has clicked ad (conversion event)",
        "user_data_has_clicked_email": "has clicked email (conversion event)",
        "user_data_brand": "brand (conversion event)",
        "user_data_device_type": "device type (conversion event)",
        "user_data_model": "model (conversion event)"
        }

Other

{
        "app_id": "app id",
        "customer_event_alias": "customer event alias"
        }

Measures

The measures below are supported, along with any additional custom-defined event names.

OPEN
        users
        Retention
        ARPPU
        LTV
        ARPU
        revenue
        PURCHASE
        ADD_TO_CART
        ADD_TO_WISHLIST
        VIEW_CART
        INITIATE_PURCHASE
        ADD_PAYMENT_INFO
        SPEND_CREDITS
        RESERVE
        CLICK_AD
        VIEW_AD
        SEARCH
        VIEW_ITEM
        VIEW_ITEMS
        RATE
        SHARE
        COMPLETE_REGISTRATION
        COMPLETE_TUTORIAL
        ACHIEVE_LEVEL
        UNLOCK_ACHIEVEMENT
        INVITE
        LOGIN
        SUBSCRIBE
        START_TRIAL
        cost
        GROSS_PROFIT
        ROI
        ROAS
        eCPA

Export Format

Example JSON Export

[
        {
        "users":200,
        "cost":"1234.45",
        "metric":"revenue",
        "measure":"ARPPU",
        "per_user":false,
        "cumulative":false,
        "data":{
        "day0":"1234.45",
        "day1":"2345.56",
        "day2":"1230.34",
        "day3":"9485.23"
        },
        "user_data_platform":"ANDROID_APP",
        "install_activity_data_tilde_advertising_partner_name":"Taptica"
        },
        {
        "users":200,
        "cost":"1234.45",
        "metric":"total_count",
        "measure":"OPEN",
        "per_user":false,
        "cumulative":false,
        "data":{
        "day0":45,
        "day1":23,
        "day2":412,
        "day3":230
        },
        "user_data_platform":"ANDROID_APP",
        "install_activity_data_tilde_advertising_partner_name":"Taptica"
        }
        ]
    

Example CSV Export

Columns are generated when exporting to CSV. The columns are:

  • measure

  • metric

  • per_user

  • cumulative

  • users

  • <dimensions>

  • <granularity bands>

measure,metric,per_user,cumulative,users,last_attributed_touch_data_tilde_advertising_partner,day0,day1,day2
        OPEN,total_count,false,false,2099,Taptica,407,0,0
        ARPPU,revenue,true,false,2099,Taptica,521.0672786,15.25,25.5
        ARPPU,revenue,false,false,1835,Applovin,616.900742,10.25314465,24.09589041
        OPEN,total_count,false,false,1835,Applovin,475,0,0
        OPEN,total_count,true,false,1760,A4G,303,0,0
        ARPPU,revenue,true,false,1760,A4G,909.0080882,14.80434783,39.46875
        OPEN,total_count,false,false,401,Twitter,65,0,0
        ARPPU,revenue,true,false,401,Twitter,1211.638854,16.94444444,25.5
        ARPPU,revenue,true,false,369,Snap,898.039303,5,0
        OPEN,total_count,false,false,369,Snap,55,0,0
        ARPPU,revenue,true,false,348,Facebook,1329.544306,0,0
        OPEN,total_count,false,false,348,Facebook,52,0,0
        OPEN,total_count,false,false,177,Apple Search Ads,1045,0,0
        ARPPU,revenue,true,false,177,Apple Search Ads,60.32139244,0,0

The above example can be viewed and downloaded here: Cohort API CSV Example.

Filename Format

The naming convention for export files is as follows:

<start_date>-<end_date>-<data_source>-<granularity>-<job_id>-<random 16 char string>

JSON Example

2024-09-23-2024-09-25-install_cohort-day-6dad4289-0cab-49cb-bfab-1be70c2b6933-edeSKgkDSkrsHGdr.json

CSV Example

2024-09-23-2024-09-25-install_cohort-day-6dad4289-0cab-49cb-bfab-1be70c2b6933-edeSKgkDSkrsHGdr.csv