Cohort API

Request headers

Use the following filter parameters to get the necessary data. 

Use the following grouping paramters to include additional columns and make your reports less granular.

• The table lists the KPIs available and their associated functions. When you call a KPI, all its functions return.
• The following KPIs always return: users, ecpi, and cost 
• Select one additional KPI per call.

Presentation of KPI functions

The following KPI format parameters set the format of the KPIs returned. 

This example contains a complete API call.

curl -L -X POST 'https://hq1.appsflyer.com/api/cohorts/v1/data/app/<insert your app_id here>?format=<insert results format here>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <cohort_api_token_placeholder. Note the token has more than 700 characters.>' \
-H 'Accept: application/json' \
--data-raw '{
    "cohort_type": "user_acquisition",
    "min_cohort_size": 1,
    "preferred_timezone": false,
    "from": "2020-01-01",
    "to": "2020-01-31",
    "filters": {
        "period": [
            0,
            1,
            2,
            10,
            30,
            60
        ],
        "geo": [
            "US",
            "CN"
        ],
        "pid": [
            "Meta ads",
            "googleadwords_int"
        ]
    },
    "preferred_currency": true,
    "aggregation_type": "on_day",
    "per_user": false,    
    "groupings": [
        "pid",
        "date"
    ],
    "kpis": [
        "sessions"
    ]
}'

import http.client
import mimetypes
conn = http.client.HTTPSConnection("hq1.appsflyer.com")
payload = "{\r\n    \"cohort_type\": \"user_acquisition\",\r\n    \"min_cohort_size\": 1,\r\n    \"preferred_timezone\": false,\r\n    \"from\": \"2020-05-01\",\r\n    \"to\": \"2020-05-10\",\r\n    \"preferred_currency\": true,\r\n    \"aggregation_type\": \"cumulative\",\r\n    \"per_user\": false,   \r\n     \"groupings\": [\r\n               \"pid\",\r\n         \"date\"\r\n        ],\r\n    \"kpis\": [\r\n        \"roas\"\r\n    ]\r\n}"
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer [Enter token here]',
  'Accept': 'application/json',
  'Content-Type': 'application/json'
}
conn.request("POST", "/api/cohorts/v1/data/app/[My App ID here]?format=csv", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
   

Example 1: Retention

Media source retention (sessions)  of users who installed the app during January on day 7, 14, and 28 

{
  "per_user": false,
  "groupings": [
    "pid"
  ],
  "filters": {
    "period": [
      7, 14, 28
    ]
  },
  "partial_data": false,
  "aggregation_type": "on_day",
  "min_cohort_size": 1,
  "cohort_type": "user_acquisition",
  "from": "2021-01-01",
  "to": "2021-01-30",
  "kpis": [
    "sessions"
  ]
}

Example 2: Campaign purchases

Cohort day 3 post-install revenue per campaign

{  
  "per_user": false,
  "groupings": [
    "c"
  ],
  "filters": {
    "period": [
      3
    ],
    "c":[
        "example_campaign_name"
    ]
  },
  "partial_data": false,
  "aggregation_type": "cumulative",
  "min_cohort_size": 1,
  "cohort_type": "user_acquisition",
  "from": "2021-01-01",
  "to": "2021-01-30",
  "kpis": [
    "Checkout Start"
  ]
}

Example 3: Yesterdays activity
What activity did users who converted (installed, re-engaged, re-attributed)  during a given conversion period perform yesterday? 

Use data available via Cohort for Data Locker. The conversion period is limited to the previous 360 days. 

The name allocated to a CSV file that returns is generated from the API query. The structure is as detailed in the table that follows.

Example CSV file name

cohort_aggregation_type_per_user_kpi_report_app_id_from_to_timezone_currency_hash.csv

Period refers to the day post-attribution, where period 0 is the attribution day. For example, a user installs the app on January 1. This is the attribution day. A purchase made on period 0 means it was made on January 1. A purchase made on period 3 means it was made on January 4. Similarly, a user who installs on January 11, this is period 0. A purchase made on January 14 would be period 3.

If your report date range is January 1 to January 11 users who attributed (installed) during this period are included in the report. No other data is included. 

• The value of the period can be one or more of the following 0-180. For example, 0, 1, 2, 30, 180. 
• If no period is specified, the default values of 0, 1, 2, and so on to 30, 60, 90, and 180 return.  

{
    "cohort_type": "user_acquisition",
    "min_cohort_size": 1,
    "preferred_timezone": false,
    "from": "2019-12-01",
    "to": "2020-01-01",
    "filters": {
        "period": [
            0,
            1,
            2
        ]
    },
    "aggregation_type": "on_day",
    "per_user": false,
    "groupings": [
        "pid"
    ],
    "kpis": [
        "revenue"
    ]
}

The figures that follow map the Cohort analytics user interface to the API parameters. The two solutions - API and user interface are similar but not identical. 

The API version has the following additional options:

• Currency selection
• Timezone selection
• Filtering by period

Difference between aggregation types