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 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
사용량 제한	초당 요청 2개 분당 요청 5개 시간당 요청 150개

Prerequisites & API Access

전제 조건

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

대행사에 API 접근권한 제공하기

광고 캠페인을 운영하는 에이전시와 협력하며 후속 데이터를 내보낼 수 있는 액세스 권한을 부여하려는 경우 코호트 Export에 대한 액세스 권한을 제공할 수 있습니다.

에이전시 팀원에게 코호트 Export에 대한 액세스 권한을 제공하려면 다음을 수행하십시오.

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.
선택 사항: 데이터 필터 추가
1. Under Data Filters, toggle any necessary data filters on/blue. Exported data will be filtered accordingly.
Save를 클릭합니다.

🚧
대행사 태그 데이터
Only show agency-tagged data 데이터 필터를 활성화하지 않은 경우 에이전시 팀원은 캠페인의 관련 여부에 관계없이 모든 캠페인과 관련된 합산 데이터를 내보낼 수 있습니다.

권한인증

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	설명	필수
Access-Token	Key that encapsulates the user's permission w.r.t an org. Obtained from the Branch Dashboard needed for authentication.	예
Content-Type	application/json	예
app_id	Application ID	예

Request Query Parameters:

파라미터	설명	필수
organization_id or app_id	Unique identifier for the organization of requested data.	예
limit	반환할 최대 결과의 수입니다. Default: 100 Min: 1 Max: 50000 (unless a higher limit is specified)	아니오
format	반환된 데이터의 형식입니다. 기본값은 csv입니다.	아니오

파라미터

설명

필수

organization_id or app_id

Unique identifier for the organization of requested data.

예

limit

반환할 최대 결과의 수입니다.

Default: 100
Min: 1
Max: 50000 (unless a higher limit is specified)

아니오

format

반환된 데이터의 형식입니다. 기본값은 csv입니다.

아니오

Request Body Parameters:

파라미터	유형	설명	필수
start_date	날짜	ISO-8601 완료 날짜로 표시되는 간격 시간 범위의 시작입니다.	예
end_date	날짜	ISO-8601 완료 날짜로 표시되는 간격 시간 범위의 마지막입니다.	예
dimensions	Array of Strings	An array representing dimension(s) to group by. See Dimensions for a complete list. 제한은 11입니다.	아니오
data_source	String	A string value representing the cohort type, one of two possible values: "install_cohort" "reengagement_cohort"	예
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.	아니오
ordered	String	ordered_by 값을 기반으로 한 응답 순서입니다. "ascending" "descending" Default: "descending"	아니오
ordered_by	String	The dimension name used for sorting, see Dimensions for a complete list.	아니오
measures	String	The cohort measures names to return. See Measures for a complete list. Limit is 3	예
granularity_band_count	정수	유저에게 반환할 코호트 이벤트 이후 시간 단위 수.	예
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	아니오
per_user	불리안(Boolean)	If true, divide each band value by the user count. Default: false	아니오
granularity	String	The time granularity that each band value will represent. Default: "day"	아니오
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).	아니오

Response Body Parameters:

파라미터	설명
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	쿼리가 실패한 경우 오류 메시지

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

내보내기 다운로드 상태

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

Request Headers:

Header	설명	필수
Access-Token	Key that encapsulates the user's permission w.r.t an org. Obtained from the Branch Dashboard needed for authentication.	예

Response Path Parameters

파라미터	설명	필수
job_id	작업의 고유 식별자	예

Request Query Parameters:

파라미터	설명	필수
organization_id or app_id	요청된 데이터의 Organization을 위한 고유 식별자입니다.	예

Response Body Parameters:

파라미터	설명
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	쿼리 상태 QUEUED RUNNING FINISHED ERROR
response_url	응답 데이터를 다운로드하기 위한 S3 URL입니다.
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"
}

부록

필터

상위 레벨의 AND에 기반하여 필터가 작동합니다. 각 차원에는 "or" 필터가 여러 개 있습니다. 예: { "user_data_os": ["IOS", "안드로이드"] }.

크기

dimension 및 필터 모두에 사용됩니다. 모든 dimension에 대해 범용 이벤트 온톨로지 이름(아래 빨간색으로 강조 표시됨)을 사용하십시오.

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_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)"
}

기타

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

측정

아래 측정 목록은 추가 커스텀 정의된 이벤트 이름과 함께 서포트 됩니다.

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

내보내기 형식

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

예:

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

전제 조건

대행사에 API 접근권한 제공하기

🚧
대행사 태그 데이터

권한인증

🚧
API Key/Access Token

API Usage

Cohort Export Request

Request Headers:

Request Query Parameters:

Request Body Parameters:

Response Body Parameters:

Example Request/Response:

내보내기 다운로드 상태

Request Headers:

Response Path Parameters

Request Query Parameters:

Response Body Parameters:

Example Request/Response:

부록

필터

크기

Install Cohort

Reengagement Cohort

유저

기타

측정

내보내기 형식

JSON

CSV

Filename Format

필터

👍Try it!

Overview

Benefits of Cohort Exports API

API Limitations

Prerequisites & API Access

전제 조건

대행사에 API 접근권한 제공하기

🚧대행사 태그 데이터

권한인증

🚧API Key/Access Token

API Usage

Cohort Export Request

Request Headers:

Request Query Parameters:

Request Body Parameters:

Response Body Parameters:

Example Request/Response:

내보내기 다운로드 상태

Request Headers:

Response Path Parameters

Request Query Parameters:

Response Body Parameters:

Example Request/Response:

부록

필터

크기

Install Cohort

Reengagement Cohort

유저

기타

측정

내보내기 형식

JSON

CSV

Filename Format

👍
Try it!

🚧
대행사 태그 데이터

🚧
API Key/Access Token