The Amp Devcenter Test Developer Hub

Welcome to the Amp Devcenter Test developer hub. You'll find comprehensive guides and documentation to help you start working with Amp Devcenter Test as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Behavioral Cohorts API

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.

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.**

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 3 phases:

Phase 1: Request a Cohort

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

Parameters

ParameterTypeDescription
props (optional)integerSet 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 Requests

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 which will only be valid for 1 minute because we expect it to be immediately accessed.

Note: The phase 3 download link 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","app_id":153957,"id_type":"BY_AMP_ID","ids":[
"123", "456", "789"],"owner":"[email protected]","published":true}
' https://amplitude.com/api/3/cohorts/upload

Parameters

ParameterTypeDescription
name (required)stringA string name to be used for the cohort.
app_id (required)integerThe project identifier for the Amplitude project containing the cohort.
id_type (required)stringThe 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 typ of the IDs should be specified in the id_type field.
owner (required)stringThe login email of the cohort's owner in Amplitude.
published (required)booleanWhether the cohort is discoverable or hidden.
existing_cohort_id (optional)stringThe 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.

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

Request

Sample JSON 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 body

ParameterTypeDescription
cohort_id (required)stringThe 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)stringThe 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 jsonAn array of json objects identifying ids to add or remove
skip_invalid_ids (optional)booleanSetting 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:

ParameterTypeDescription
ids (required)list of stringList of ids to add or remove.
id_type (required)stringThe 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)stringThe operation to apply on ids field. Valid options are: - ADD - REMOVE

Response

Possible 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

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

Response Parameters (for 200 response):

ParameterTypeDescription
cohort_idstringThe id of an existing cohort that the membership information was updated for.
memberships_resultlist of memberships_result jsonAn array of json objects identifying result of membership update (add or remove) operation

Response memberships_result json

ParameterTypeDescription
skipped_idslist of stringList of ids that was skipped (fail, invalid, etc.) in this membership operation entry
id_typestringThe type of id that was sent for the ids field in this membership operation entry
operationstringThe operation that was applied on ids field in this membership operation entry

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

Failed (non 200) response body

{
    "error": {
        "message": "Cohort with id xxxxxxxxxxx not found",
        "code": 214
    }
}

Response body (for non 200 response):

ParameterTypeDescription
errorerror jsonThe detail information of the error

Response error json:

ParameterTypeDescription
messagestringError message describing the error
codeintInternal error code
metadata (optional)jsonFor 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.

Updated 4 days ago


Behavioral Cohorts API


Suggested Edits are limited on API Reference Pages

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