👍

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에 대한 액세스 권한을 제공하려면 다음을 수행하십시오.

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

🚧

대행사 태그 데이터

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입니다.

아니오

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>