Cohort API

👍
Try it!
Try out the Cohort Export API using your Branch data via the API reference here

Overview

Benefits of Cohort Exports API

The Branch Cohort Exports allows you to programmatically query and export Cohort analytics.

API Limitations

Limitation	Details
Max number of records returned by API	50,000 We may define dynamic record limits based on app_id/org_id.
Export Window	Rolling 2 year window
Max number of dimensions	11
Max number of measures	5
Max number of days that can be queried at a time	90
Rate Limits	2 requests per second 5 requests per minute 150 requests per hour

Prerequisites & API Access

Prerequisites

In order to access the Cohort Exports, a user will need to have both Aggregate Data and Export access.

Providing Agencies API 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 Exports.

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

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.

🚧
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 Exports 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.

Learn how to retrieve your API key (a.k.a. Access Token).

🚧
API Key/Access Token
In order to retrieve or reset your API Key/Access Token, you must have access to the Organizational Level of the Branch account. This functionality is not present at the App Level

API Usage

Cohort 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 w.r.t an org. Obtained from the Branch Dashboard needed for authentication.	Yes
Content-Type	application/json	Yes
app_id	Application ID	Yes

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 specified)	No
format	Format of returned data. Defaults to csv.	No

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 specified)

format

Format of returned data. Defaults to csv.

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 Dimensions for a complete list. Limit is 11.	No
data_source	String	A string value representing the cohort type, one of two possible values: "install_cohort" "reengagement_cohort"	Yes
filters	Array of Strings	Keys are the 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 Dimensions for a complete list.	No
measures	String	The cohort measures names to return. See Measures for a complete list. Limit is 3	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 (result from iOS 14.5 privacy changes).	No

Response Body Parameters:

Parameter	Description
job_id	Unique identifier used to retrieve job status and data.
code	HTTP code, 2xx/4xx/5xx that represents the outcome of the status request.
status_url	Url to curl to retrieve job status and data (see Export Download Status request below).
error_message	Error message 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": "2022-05-30",
        "end_date": "2022-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"
}

Export Download Status

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

Request Headers:

Header	Description	Required
Access-Token	Key that encapsulates the user's permission w.r.t an org. Obtained from the Branch Dashboard needed for authentication.	Yes

Response Path Parameters

Parameter	Description	Required
job_id	Unique identifier for job	Yes

Request Query Parameters:

Parameter	Description	Required
organization_id or app_id	Unique identifier for organization of requested data.	Yes

Response Body Parameters:

Parameter	Description
code	Response Code, 1xx/2xx/4xx/5xx. Note: a 1xx will denote a QUEUED or RUNNING status. HTTP code represents the outcome of the status request.
status	Status of the query. QUEUED RUNNING FINISHED ERROR
response_url	S3 url for downloading the response data.
error_message	Error message corresponding to failure reason 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/2022-05-30-2022-05-31-install_cohort-day-7636f4ab-34d1-47d1-a9c9-7cbe364953ec-xxxxxxxxxxx.json?Signature=D0zi5Jkhl073ixxxxxxxxxxxxAccessKeyId=xxxxxxxxxxxxx&Expires=1655145468"
}

Appendix

Filters

Filters work based on AND at the top level. Each dimension can have multiple "or" filters e.g. { "user_data_os": ["IOS", "ANDROID"] }.

Dimensions

Used for both dimensions and filters. For all dimensions, use the universal event ontology name (highlighted in red below).

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 list of 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

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"
   }
]

CSV

Columns are generated when exporting to CSV:
measure, metric, per_user, cumulative, user, cost, <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/downloaded: Cohort API CSV Example

Filename Format

The filename naming convention used is as follows:
start_date-end_date-data_source-granularity-job_id-random 16 character string

Example:

2019-09-23-2019-09-25-install_cohort-day-6dad4289-0cab-49cb-bfab-1be70c2b6933-edeSKgkDSkrsHGdr.<json | csv>

Cohort API

👍
Try it!

Overview

Benefits of Cohort Exports API

API Limitations

Prerequisites & API Access

Prerequisites

Providing Agencies API Access

🚧
Agency-Tagged Data

Authentication

🚧
API Key/Access Token

API Usage

Cohort Export Request

Request Headers:

Request Query Parameters:

Request Body Parameters:

Response Body Parameters:

Example Request/Response:

Export Download Status

Request Headers:

Response Path Parameters

Request Query Parameters:

Response Body Parameters:

Example Request/Response:

Appendix

Filters

Dimensions

Install Cohort

Reengagement Cohort

User

Other

Measures

Export Format

JSON

CSV

Filename Format

Filters

👍Try it!

Overview

Benefits of Cohort Exports API

API Limitations

Prerequisites & API Access

Prerequisites

Providing Agencies API Access

🚧Agency-Tagged Data

Authentication

🚧API Key/Access Token

API Usage

Cohort Export Request

Request Headers:

Request Query Parameters:

Request Body Parameters:

Response Body Parameters:

Example Request/Response:

Export Download Status

Request Headers:

Response Path Parameters

Request Query Parameters:

Response Body Parameters:

Example Request/Response:

Appendix

Filters

Dimensions

Install Cohort

Reengagement Cohort

User

Other

Measures

Export Format

JSON

CSV

Filename Format

👍
Try it!

🚧
Agency-Tagged Data

🚧
API Key/Access Token