Behavioral Cohorts API

Updated

Important Note:

This article has been moved to our new Developer Center. For the latest info, please see Behavioral Cohorts API

Table of Contents

The Behavioral Cohorts API can be used to list all your cohorts in Amplitude, export a cohort in Amplitude, or upload a cohort. In the examples below the parameters are highlighted in purple, and the values in red are what you need to replace with the parameters you are specifically interested in. 

IMPORTANT NOTES:

Behavioral Cohorts Download API is capped at 500 API calls per month on Growth and Enterprise plans.

Please note: Export size for cohorts is limited to 10 million users and we also have a concurrency cap of 5 requests across cohort downloads and our Dashboard REST API.

 

Table of Contents

 

Listing All Cohorts

Get all discoverable cohorts for an app.

Authenticate via basic authentication with the credentials API_Key:Secret_Key.

GET https://amplitude.com/api/3/cohorts

 

Response

The response is a JSON object with the following schema:

{
    "cohorts": [
        { COHORT_OBJECT },
        ...
        { COHORT_OBJECT },
    ]
}

Each COHORT_OBJECT has the following schema:

{
    "lastComputed": timestamp,
    "owners": string[],
    "description": string,
    "definition": { COHORT_DEFINITION },
    "published": boolean,
    "archived": boolean,
    "name": string,
    "appId": string,
    "lastMod": timestamp,
    "type": string,
    "id": string,
    "size": integer
}

 

Example Request

curl -u API_Key:Secret_Key 'https://amplitude.com/api/3/cohorts'

 

Getting One Cohort

Get a discoverable cohort using its string ID. You can find all of the IDs (up to 10 million) by using the list API above.

Authenticate via basic authentication with the credentials API_Key:Secret_Key.

Cohort Download uses an async API, and is broken into 2 phases:

Phase 1: Request a Cohort

GET https://amplitude.com/api/5/cohorts/request/COHORT_ID

Parameters

Parameter Description
props (optional)
integer

Set to 0 for optimal results. props=0 will only include Amplitude IDs and user IDs in the response object; user properties are excluded.

Set to 1 to include user properties in the response object in addition to Amplitude IDs and user IDs.
propKeys (optional)
string[]		 One or more user properties to include in the response. If left undefined and props=1, response object will return ALL available user properties.

 

Response

The response is a 202 response code with the following JSON object:

{
    'request_id': <request_id>,
    'cohort_id': <cohort_id>
}

Errors: auth fails or cohort id is incorrect/not accessible

Note: 'request_id' is transient, and only valid for a few days

 

Example Request

1b3b3c4 is the cohort ID in this example:

curl -u API_Key:Secret_Key
'https://amplitude.com/api/5/cohorts/request/1b3b3c4?props=0'

2a2b3c4 is the cohort ID in this example:

curl -u API_Key:Secret_Key
'https://amplitude.com/api/5/cohorts/request/2a2b3c4?props=1&propKeys=country&propKeys=city'

 

Phase 2: Poll Request Status

GET https://amplitude.com/api/5/cohorts/request-status/REQUEST_ID

Response

When the job is still running, a 202 response code and the following JSON object will be returned:

{
    'request_id': <request_id>,
    'cohort_id': <cohort_id>,
    'async_status': 'JOB INPROGRESS'
}

When the job has completed, a 200 response code and the following JSON object will be returned:

{
    'request_id': <request_id>,
    'cohort_id': <cohort_id>,
    'async_status': 'JOB COMPLETED'
}

 

Phase 3: Download File

The exported cohort file is now ready to be downloaded from:

GET https://amplitude.com/api/5/cohorts/request/REQUEST_ID/file

This will redirect with a 302 response code to a pre-signed Amazon S3 download URL.

Note: The download will only be available for 7 days after the request is completed

 

Refreshing a Cohort

When retrieving a cohort, it will automatically be refreshed prior to downloading it.

IMPORTANT NOTE: Refreshing a cohort manually via this API in Amplitude 2.0 is no longer necessary and is not supported. For queries run with cohorts, the cohort will automatically be refreshed prior to running the query.

 

Uploading a Cohort of IDs

A new cohort can be generated or an existing cohort can be updated by uploading a set of User IDs or Amplitude IDs. Authenticate via basic authentication with the credentials API_Key:Secret_Key.

POST https://amplitude.com/api/3/cohorts/upload

Here is an example request:

curl -i --user "$API_KEY:$SECRET_KEY" -H "Content-Type: application/json" --data '
{
  "name":"Test Cohort",
  "id_type":"BY_AMP_ID",
  "ids":["123","456","789"],
  "owner":"datamonster@amplitude.com",
  "published":true
}' https://amplitude.com/api/3/cohorts/upload

 

Parameters

Parameter Description
name (required)
string		 A string name to be used for the cohort.
id_type (required)
string

The type of id being sent in the ids field. Valid options are:

  • BY_AMP_ID
  • BY_USER_ID
ids (required)
string[]		 One or more user or Amplitude IDs to include in the cohort. The type of the IDs should be specified in the id_type field.
owner (required)
string		 The login email of the cohort's owner in Amplitude.
published (required)
boolean		 Whether the cohort is discoverable or hidden.
existing_cohort_id (optional)
string

The id of an existing cohort. This will replace the contents for the specified cohort with the ids being uploaded by this request.

e.g. '1a2bc3d' is your cohort's id, and it can be found in your cohort's URL.  https://analytics.amplitude.com/demo/cohort/1a2bc3d

 

Response

The response is a JSON object with the following schema:

{
    "cohort_id": "COHORT_ID"
}

 

Modifying membership (ids)

You can perform incremental update (add / remove) to existing cohort's membership by submitting a POST request. Authenticate via basic authentication with the credentials API_Key:Secret_Key.

POST https://amplitude.com/api/3/cohorts/membership

Here is an example request:

curl -i --user "$API_KEY:$SECRET_KEY" -H "Content-Type: application/json" --data '
{
 "cohort_id":"1a2bc3d",
 "memberships": [
 {
 "ids" : ["111",”222”],
 "id_type" : "BY_ID",
 "operation" : "ADD"
 },
 {
 "ids" : ["333",”444”],
 "id_type" : "BY_ID",
 "operation" : "REMOVE"
 },
 {
 "ids" : ["asd",”qwe”],
 "id_type" : "BY_NAME",
 "operation" : "ADD"
 }
 ],
 "skip_invalid_ids":true,
}' https://amplitude.com/api/3/cohorts/membership

Request

Parameter Description
cohort_id (required)
string		 The id of an existing cohort. This will update the membership for the specified cohort with the ids being uploaded in this request.
count_group (optional)
string

The count group of the given ids. This must be the same as the cohort’s existing count group. Count_group is default to User if not provided.
memberships (required)
list of membership json		 An array of json objects identifying ids to add or remove
skip_invalid_ids (optional)
boolean		 Setting skip_invalid_ids to false will abort request if request contain invalid ids (without modifying the membership of the cohort). Setting skip_invalid_ids to true will skip invalid ids while applying the remaining valid ids. skip_invalid_ids is default to true if not provided.

Request membership json:

Parameter Description
ids (required)
list of string		 List of ids to add or remove
id_type (required)
string

The type of id being sent in the ids field. Valid options are:

  • BY_ID
  • BY_NAME

For User count_group, BY_ID is amplitude id and BY_NAME is user id. For any other count_group, BY_ID is group id and BY_NAME is group name.

operation (required)
string

The operation to apply on ids field. Valid options are:

  • ADD
  • REMOVE

 

Response

Response Code:
200 - Success (membership change applied)
400 - Required field missing
400 - Membership json empty or invalid (required fields in membership empty or invalid)
400 - id_type and/or operation invalid
400 - existing cohort id not found or is not manual upload or cohort’s count group does not match
400 - Invalid ids given in membership and skip_invalid_ids=False
401 - unauthorized
429 - request throttled or cohort is currently being modified
500 - Internal server error

The response is a JSON object with the following schema:

Response body (for 200 response):

Parameter Description

cohort_id

string

 The id of an existing cohort that the membership information was updated for.
memberships_result list of memberships_result json

An array of json objects identifying result of membership update (add or remove) operation

 Response memberships_result json:

Parameter Description
skipped_ids
list of string		 List of ids that was skipped (fail, invalid, etc.) in this membership operation entry
id_type
string

The type of id that was sent for the ids field in this membership operation entry
operation 
string

The operation that was applied on ids field in this membership operation entry

 Response body (for non 200 response):

Parameter Description
error
error response json		 The detail information of the error

 Response error json:

Parameter Description
message
string		 Error message describing the error
code
int

Internal error code

metadata (optional)
json

For bad request error (400) with invalid id while skip_invalid_ids=False, this field contains the cohort_id and memberships_result (list of membership json). The memberships_result’s skipped_ids can help identify which ids was invalid in which operation. For other errors, this field is not present.

Example:

Success (200) response Body:

{
   "cohort_id": "COHORT_ID"
   "memberships_result": [
     {
      "skipped_ids" : [”222”],
      "id_type" : "BY_ID",
      "operation" : "ADD"
     },
     {
      "skipped_ids" : [],
      "id_type" : "BY_ID",
      "operation" : "REMOVE"
     },
     {
      "skipped_ids" : ["asd",”qwe”],
      "id_type" : "BY_NAME",
      "operation" : "ADD"
     }
  ]
}

Failed (non 200) response Body:

{
    "error": {
        "message": "Failed request as invalid id (while skip_invalid_ids=False) was found",
        "code": 216,
        "metadata": {
            "cohort_id": "local_zfsje5i",
            "memberships_result": [{
                "operation": "ADD",
                "skipped_ids": ["9999999999999999999"],
                "id_type": "BY_NAME"
            }]
        }
    }
}
{
    "error": {
        "message": "Cohort with id xxxxxxxxxxx not found",
        "code": 214
    }
}
Was this article helpful?
2 out of 2 found this helpful
Have more questions? Check out the Amplitude Community.
Return to top