> For the complete documentation index, see [llms.txt](https://help.branch.io/llms.txt).

# Cohort API Overview

## Overview

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

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

### Benefits of Cohort API

Cohort Analytics data lets you 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<br><br>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.<br>5 requests per minute.<br>150 requests per hour. |

## Getting started

### Before you begin

To use the Cohort API, you first need to:

- Create a [Branch account](https://dashboard.branch.io/).
- Implement the appropriate Branch SDK into your mobile app ([iOS](https://help.branch.io/developer-hub/ios-sdk-overview.md) | [Android](https://help.branch.io/developer-hub/android-sdk-overview.md)).
- Make sure you have the appropriate permissions set on your user account. See the "Access" [section](https://help.branch.io/apidocs/cohort/overview.md#access) for more.

### Access

#### General access

To access the Async Aggregate API, a user must have both **Aggregate Data** and **Export** [access](https://help.branch.io/account-hub/default-access-levels-users-roles-permissions.md#access-levels) 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**, select **Account Settings**.
2. On the **Account Settings** page, select the **Agencies** tab.
3. Expand the agency in question, find the agency team member you want to give access to, hover over the button in the **Actions** column, and select **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. Exported data will be filtered accordingly.
6. Select **Save**.

![](https://help.branch.io/img/b1af170-agency-ad-partner-invite-3-.png "agency-ad-partner-invite.png")

> **Agency-tagged data**
>
> If you do not enable the "Only Show Agency-Tagged Data" filter, the agency team member can export aggregate data associated with all of your campaigns, regardless of whether they are associated with them or not.

### Authentication

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

**Legacy Branch**

To retrieve your credentials in the [legacy Branch experience](https://help.branch.io/marketer-hub/branch-dashboard-overview.md):

1. Navigate to the **Account → Settings → User** [tab](https://dashboard.branch.io/account-settings/profile).
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.

**New Branch**

To retrieve your credentials in the [new Branch experience](https://help.branch.io/account-hub/credentials-new.md):

1. Navigate to the **Configuration → Security & Access → Credentials** [tab](https://branchdocs.app.link/apis-to-credentials).
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](https://help.branch.io/account-hub/credentials-new.md) to learn more about managing your Branch credentials.

## Usage

### Export Cohort Analytics

#### Request info

**Export request**

```http
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 regard to an organization. Obtained from Branch. Needed for [authentication](https://help.branch.io/apidocs/aggregate/overview.md#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 the requested data. | **Yes** |
| `limit` | The maximum number of results to return.<br><br>**Default**: 100<br>**Min**: 1<br>**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](https://help.branch.io/apidocs/cohort/overview.md#dimensions) for a complete list.<br><br>The limit is 11. | No |
| `data_source` | String | A string value representing the cohort type. Can be either:<br><br>- `"install_cohort"`<br>- `"reengagement_cohort"` | **Yes** |
| `filters` | Array of Strings | Keys are the same as dimensions. Values are an array of values to match for the dimension.<br><br>An object defining filters to match or disallow certain values. | No |
| `ordered` | String | Order of the response, based on the `ordered_by` value.<br><br>- `"ascending"`<br>- `"descending"`<br>**Default**: `"descending"` | No |
| `ordered_by` | String | The dimension name used for sorting.<br><br>See the "Dimensions" [section](https://help.branch.io/apidocs/cohort/overview.md#dimensions) for a complete list. | No |
| `measures` | String | The cohort measure names to return.<br><br>The limit is **3**.<br><br>See the "Measures" [section](https://help.branch.io/apidocs/cohort/overview.md#measures) 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.<br><br>**Default**: `false` | No |
| `per_user` | Boolean | If `true`, divide each band value by the user count.<br><br>**Default**: `false` | No |
| `granularity` | String | The time granularity that each band value represents.<br><br>**Default**: `"day"` | No |
| `enable_install_recalculation` | Boolean | If `true`, Branch will dedupe 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](https://help.branch.io/apidocs/cohort/overview.md#get-export-download-status). |
| `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

**Request (cURL)**

```curl
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
}'
```

**Response (JSON)**

```json
{
  "code" : 200,
  "job_id" : "7636f4ab-34d1-47d1-a9c9-xxxxxxxx",
  "status_url" : "https://api2.branch.io/v2/analytics/xxxxxxxxx"
}
```

### Get export download status

```http
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 regard to an organization. Obtained from Branch. Needed for [authentication](https://help.branch.io/apidocs/aggregate/overview.md#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 the requested data. | **Yes** |

#### Response info

**Response body parameters**

| Parameter | Description |
| --- | --- |
| `code` | HTTP response code representing the outcome of the status request.<br><br>**Note**: A `1xx` code denotes a `QUEUED` or `RUNNING` status. |
| `status` | Status of the query.<br><br>Possible status values:<br>`QUEUED`<br>`RUNNING`<br>`FINISHED`<br>`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

**Request (cURL)**

```curl
curl 'https://api2.branch.io/v2/analytics/<job_id>?organization_id=<organization_id>' -H 'Access-Token:<branch_access_token>'
```

**Response (JSON)**

```json
{
  "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, for example, `{ user_data_os": ["IOS", "ANDROID"] }`.

### Dimensions

#### Install cohort

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
[
  {
    "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](https://help.branch.io/files/cohort-api-csv-example.csv).

#### 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`