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 1 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
- Getting One Cohort
- Refreshing a Cohort
- Uploading a Cohort of IDs
- Modifying membership (ids)
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 1 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. 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:
|
| 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:
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:
|
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) |
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
}
}