Cohort Exports

Overview

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

  • Max number of records returned by API: 50,000.
    • We may define dynamic record limits based on app_id/org_id.
  • Max month lookback: 24
  • Max number of dimensions: 11
  • Max number of measures: 5
  • Max number of days that can be queried at a time: 90

Authentication

Calls to the Cohort Exports require an _apikey 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)

Organization Level Access Required

In order to retrieve or reset your API Key/Access Token, you must have access to the Organization level of the account. This functionality is not present at the app level.

Rate Limits

The Cohort Exports includes the following rate limits:

  • 2 requests per second
  • 5 requests per minute
  • 150 requests per hour

API Access

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

image

For more details on how to give a user the required access, please follow Granting a User 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:

  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.

image

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.

Export Request

POST /v2/analytics
Content-Type: application/json
Host: api2.branch.io

Request

HTTP Headers:

Parameter
Required
Definition

Access-Token

yes

Key that encapsulates the users permission w.r.t an org.

URL Query Parameters:

Parameter
Required
Definition
Values

organization_id

yes

Unique identifier for organization of requested data.

limit

no

The maximum number of results to return.


Default: 50000


Min: 50000


Max: 50000 (unless a higher limit is specified)

integer

format

no

Format of returned data. Defaults to csv.

csv/json

Body Parameters:

Parameter
Required
Definition
Values

start_date

yes

The start of the interval time range represented as an ISO-8601 complete date.

YYYY-MM-DD

end_date

yes

The end of the interval time range represented as an ISO-8601 complete date.

YYYY-MM-DD

dimensions

no

An array representing dimension(s) to group by.


Limit is 11.

See Dimensions for complete list

data_source

yes

A string value representing the cohort type.

One of 2 possible values:



  • install_cohort

  • reengagement_cohort

filters

no

An object defining filters to match or disallow certain values.

Object. Keys are same as dimensions. Values are an array of values to match for the dimension.

ordered

no

Order of response based on ordered_by value.


Default: descending.

descending or ascending

ordered_by

no

The dimension used for sorting

Dimension name. See Dimensions for complete list.

unique

no

Whether or not to return unique values.


Default: false

True, false

measures

yes

The cohort measures to return. Limit is 3.

Measure name. See Measures for complete list.

granularity_band_count

yes

Number of time units since the cohort event to return to the user.

Integer.

cumulative

noe

If true, sum across bands so that a given band value is the sum of all preceding values plus the band value. Default: false

true/false

per_user

no

If true, divide each band value by the user count. Default: false.

true/false

granularity

no

The time granularity that each band value will represent. Default: day

day, week, or month.

Example Request:

curl -X POST 'http://api2.branch.io/v2/analytics?organization_id=<organization_id>&limit=50000&format=json' -H 'Access-Token:<branch_access_token>' -H 'content-type:application/json' -d '{
        "start_date": "2019-09-23",
        "end_date": "2019-09-24",
        "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"
}'

Response

Parameter
Definition
Values

job_id

Unique identifier used to retrieve job status and data

Unique UUID

code

HTTP code representing the outcome of the export request.

2xx/4xx/5xx.

status_url

Url to curl to retrieve job status and data.

See below

error_message

Error message if the export call fails

Error message

Status_url value:

https://api2.branch.io/v2/analytics/<job_id>

Export Download Status

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

Request

HTTP Headers:

Parameter
Required
Definition
Values

Access-Token

yes

Key that encapsulates the users permission w.r.t an org.

URL Query Parameters:

Parameter
Required
Definition

organization_id

yes

Unique identifier for organization of requested data.

Path Parameters:

Parameter
Required
Definition

job_id

yes

Unique identifier for job

Example Request:

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

Response

Parameter
Definition
Values

status

Status of they query.

QUEUED, RUNNING, FINISHED, ERROR

code

HTTP code representing the outcome of the status request.

1xx/2xx/4xx/5xx. Note: a 1xx will denote a QUEUED or RUNNING status.

response_url

S3 url for downloading the response data.

S3 url

error_message

Error message if the query failed

error message corresponding to failure reason

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

Reengagement cohort

{
  "reengagement_activity_attributed": "attributed",
  "reengagement_activity_event_name": "event name",
  "reengagement_activity_touch_type": "type",
  "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_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"
}

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

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
SPENG_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: measure, metric, per_user, cumulative, user, cost, <dimensions>, <granularity bands>

Example:

[https://drive.google.com/file/d/1CDVfwoh5eetDQ79MpU7ZAKxSPah8A2F-/view?usp=sharing](https://drive.google.com/file/d/1CDVfwoh5eetDQ79MpU7ZAKxSPah8A2F-/view?usp=sharing)

Filename {#filename}

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>

Updated 5 months ago

Cohort Exports


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.