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