Behavioral Cohorts API

Limits and considerations

For Growth and Enterprise plans, the Behavioral Cohorts Download API has a limit of 500 requests per month. Each Get one cohort request counts toward this limit. Use the Get usage endpoint to check your current usage.
Amplitude supports a maximum cohort size of 2 million users. For larger cohorts, use one of the following:
- Create a cohort sync to Amazon Kinesis
- Create a cohort sync to a custom destination with a Webhook
- Create a cohort sync to Profile API
The concurrency limit is 5 requests across cohort downloads and the Dashboard REST API.
Cohort Download uses an asynchronous API. To get a cohort, complete three steps:
1. Request a single cohort.
2. Poll the cohort status.
3. Download the file.
Cohort Download limits single cohort requests to 60 requests per 10 minutes per app, and 4 parallel requests per minute per app.
Amplitude limits single requests to 100,000 identifiers.

Get all cohorts

Get all discoverable cohorts for an app. Use the id for each cohort returned in the response to get a single cohort.

curl

curl --location --request GET 'https://amplitude.com/api/3/cohorts' \
-u '{api_key}:{secret_key}'

Query parameters

Name	Description
`includeSyncInfo`	Optional. Boolean. Set to `true` to include cohort sync metadata in the response. The response excludes one-time and disabled syncs.

Response

The response is a JSON object with this schema:

json

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

Each COHORT_OBJECT returned has this schema:

json

{
    "appId": integer,
    "archived": boolean, // whether cohort is archived
    "definition": { COHORT_DEFINITION }, // Amplitude internal representation of Cohort Definition
    "description": string,
    "finished": boolean, // Amplitude internal use to decide whether a training cohort has finished ML training
    "id": string,
    "name": string,
    "owners": string[],
    "viewers": string[],
    "published": boolean, // whether cohort is discoverable by other users
    "size": integer,
    "type": string, // Amplitude internal representation on different cohort types
    "lastMod": timestamp, // last modified date
    "createdAt": timestamp,
    "lastComputed": timestamp,
    "hidden": boolean, // Amplitude internal use case to hide a cohort
    "metadata": string[], // cohort created from funnel/microscope might have this
    "view_count": integer,
    "popularity": integer, // cohort created from chart might have this
    "last_viewed": timestamp,
    "chart_id": string, // cohort created from chart will have this
    "edit_id": string, // cohort created from chart will have this
    "is_predictive": boolean,
    "is_official_content": boolean,
    "location_id": string, // cohort created from chart might have this
    "shortcut_ids": string[],
    "syncMetadata": COHORT_SYNC_METADATA[]
}

Each COHORT_SYNC_METADATA has this schema:

json

{
    "target": string,
    "frequency": string, // support minute (real-time), hourly, daily
    "last_successful": timestamp,
    "last_failure": timestamp,
    "params": { COHORT_SYNC_LEVEL_PARAM }
}

The following is a sample result:

json

"cohorts": [{
    "appId": 123456,
    "archived": false,
    "definition": {
        "version": 3,
        "countGroup": {
            "name": "User",
            "is_computed": false
        },
        "cohortType": "UNIQUES",
        "andClauses": [{
            "negated": false,
            "orClauses": [{
                "type": "event",
                "time_type": "rolling",
                "time_value": 30,
                "offset": 0,
                "interval": 1,
                "type_value": "_active",
                "operator": ">=",
                "operator_value": 1,
                "group_by": [],
                "metric": null
            }]
        }],
        "referenceFrameTimeParams": {}
    },
    "description": "test description",
    "finished": true,
    "id": "id_12345",
    "name": "Test Cohort 1",
    "owners": [
        "demo@amplitude.com"
    ],
    "viewers": [],
    "published": true,
    "size": 111,
    "type": "redshift",
    "lastMod": 1679437294,
    "createdAt": 1679437288,
    "lastComputed": 1679440233,
    "hidden": false,
    "metadata": null,
    "view_count": null,
    "popularity": null,
    "last_viewed": null,
    "chart_id": null,
    "edit_id": null,
    "is_predictive": false,
    "is_official_content": false,
    "location_id": null,
    "shortcut_ids": [],
    "syncMetadata": [{
        "target": "braze",
        "frequency": "hourly",
        "last_successful": "2023-03-21T16:09:58.848454-07:00",
        "last_failure": null,
        "params": {
            "user_id": "demo@amplitude.com"
        }
    }]
}],

Get one cohort

Get a discoverable cohort using its cohort_id. This is step one of the cohort download operation. Use the request_id returned in the response to poll export status.

curl

curl --location --request GET 'https://amplitude.com/api/5/cohorts/request/id'
-u '{api_key}:{secret_key}'

Path parameters

Name	Description
`id`	Required. Cohort ID.

Query parameters

Name	Description
`props`	Optional. Integer. Set to `1` to include user properties in the response object. Set to `0` or unset if the request keeps timing out.
`propKeys`	Optional. `string[]`. One or more user properties to include in the response. Add as many `propKeys` parameters as needed. If undefined and `props=1`, the response object returns all available user properties.

Response

A single cohort request returns a 202 response code with the following JSON object:

json

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

If your authorization or the cohort_id is invalid, the request returns an error.

Get request status

Poll the request status using the request_id retrieved for the cohort. This is step two of the cohort download operation.

curl

curl --location --request GET 'https://amplitude.com/api/5/cohorts/request-status/:request_id' \
-u '{api_key}:{secret_key}''

Path parameters

Name	Description
`request_id`	Required. The request ID retrieved with the get one cohort request.

Response

If the job is still running, the request status returns a 202 code and the async_status JOB INPROGRESS.

json

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

If the job has finished running, the request status returns a 200 code and the async_status JOB COMPLETED.

json

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

Download cohort

After the job finishes running, download the cohort. The following is a basic request.

curl

curl --location --request GET 'https://amplitude.com/api/5/cohorts/request/:requestId/file' \
-u '{api_key}:{secret_key}'

Path parameters

Name	Description
`request_id`	Required. The request ID retrieved with the get one cohort request.

For small cohorts, the response body contains the cohort data.
For large cohorts, you must download the data. The response redirects with a 302 response code to a pre-signed Amazon S3 download URL. The download URL is valid for one minute, so access it immediately.
The API request link (https://amplitude.com/api/5/cohorts/request/:requestId/file) is valid for seven days. During those seven days, you can make the same request to get a new S3 download link. Each S3 link is valid for one minute.
Most API clients automatically download the data from the S3 link. If your API client does not automatically download the cohort, you have one minute to access it manually.

Get usage

Check your current monthly usage and limit for the Behavioral Cohorts Download API.

curl

curl --location --request GET 'https://amplitude.com/api/3/cohorts/usage' \
-u '{api_key}:{secret_key}'

Response

json

{
    "rest_download": {
        "limit": 500,
        "usage": 42,
        "resets_at": "2026-06-01T00:00:00"
    }
}

Usage resets on the first of each month (UTC).

Upload cohort

Generate a new cohort or update an existing cohort by uploading a set of User IDs or Amplitude IDs. The following is a basic request example with placeholder values.

bash

curl --location --request POST 'https://amplitude.com/api/3/cohorts/upload' \
--header 'Content-Type: application/json' \
-u '{api_key}:{secret_key}''
--data-raw '{
    "name": "Cohort Name",
    "app_id": amplitude_project,
    "id_type": "BY_AMP_ID",
    "cg": "group_id",
    "ids": [
            "amplitude_id",
            "amplitude_id"
    ],
    "owner": "cohort_owner",
    "published": true
}'

Body parameters

Parameter	Description
`name`	Required. String. A name for the cohort.
`app_id`	Required. Integer. An identifier for the Amplitude project containing the cohort.
`id_type`	Required. String. The kind of ID sent in the ids field. Valid options are `BY_AMP_ID` or `BY_USER_ID`.
`cg`	Optional. String. Enter the name of an existing group to create a cohort based on it.
`ids`	Required. String[]. One or more user or Amplitude IDs to include in the cohort. Specify the ID type 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.
`skip_save`	Optional. Boolean. Set to `true` if you want to validate the upload without saving. Default is `false`.
`skip_invalid_ids`	Optional. Boolean. Set to `true` to skip invalid IDs and upload the remaining valid IDs. Set to `false` to end the upload if the request has invalid IDs. Default is `true`.
`existing_cohort_id`	Optional. String. The ID of an existing cohort. The IDs uploaded in the request replace the contents of the specified cohort. For example, `1a2bc3d` is your cohort's ID, found in the cohort's URL: `https://analytics.amplitude.com/accountname/cohort/1a2bc3d`.

Response

The response is a JSON object with this schema:

json

{
    "cohortId": "COHORT_ID",
    "metadata": {
        "matched": 1234,
        "totals": 1232,
        "invalid_ids_sample": ["INVALID_ID1", "INVALID_ID2"]
    }
}

Response errors

Parameter	Type	Description
error	error json	Error details.

Upload cohort error response JSON

Parameter	Description
`http_code`	Integer. Provides the HTTP error, if available.
`type`	String. Describes the type of error.
`message`	String. Describes the error.
`metadata`	JSON object. Describes in more detail the cause of the error. For example, which user ID values are invalid.

Update cohort membership

Add and remove IDs to update existing cohort membership incrementally.

bash

curl --location --request POST 'https://amplitude.com/api/3/cohorts/membership' \
--header 'Content-Type: application/json' \
-u '{api_key}:{secret_key}' \
--data-raw '{
    "cohort_id": "COHORT_ID",
    "memberships": [
        {
            "ids": [
                "ID",
                "ID"
            ],
            "id_type": "BY_ID",
            "operation": "ADD"
        },
        {
            "ids": [
                "ID",
                "ID"
            ],
            "id_type": "BY_ID",
            "operation": "REMOVE"
        },
        {
            "ids": [
                "name",
                "name"
            ],
            "id_type": "BY_NAME",
            "operation": "ADD"
        }
    ],
    "skip_invalid_ids": true
}

Request body

Parameter	Description
`cohort_id`	Required. String. The ID of an existing cohort. The IDs uploaded in the request update the membership of the specified cohort.
`count_group`	Optional. String. The count group of the given IDs. The count group must match the cohort's existing count group. `count_group` defaults to `User`.
`memberships`	Required. List of membership JSON. An array of JSON objects identifying IDs to add or remove.
`skip_invalid_ids`	Optional. Boolean. Set to `false` to end the request without updating cohort membership if the request has invalid IDs. Set to `true` to skip invalid IDs and apply the remaining valid IDs. Default is `true`.

Memberships request JSON

Parameter	Description
`ids`	Required. String[]. List of IDs to add or remove.
`id_type`	Required. String. The kind of ID sent in the `ids` field. Valid options are `BY_ID` and `BY_NAME`. For the `User` count group, `BY_ID` is the Amplitude ID and `BY_NAME` is the user ID. For any other count group, `BY_ID` is the group ID and `BY_NAME` is the group name.
`operation`	Required. String. The operation to apply on `ids` field. Valid options are: `ADD` and `REMOVE`

Response

Parameter	Description
`cohort_id`	String. The ID of the existing cohort whose membership information was updated.
`memberships_result`	List of `memberships_result` JSON. An array of JSON objects identifying the result of the membership update operation.

Memberships response JSON

Parameter	Description
`skipped_ids`	List of strings. List of skipped IDs in the membership operation entry.
`id_type`	String. The kind of ID sent for the `ids` field in this membership operation entry.
`operation`	String. The operation applied on `ids` field in this membership operation entry

Was this helpful?

Behavioral Cohorts API

Limits and considerations

Get all cohorts

Query parameters

Response

Get one cohort

Example: Get a cohort with specific properties

Example: Get cohort with all properties

Path parameters

Query parameters

Response

Get request status

Example: Get the status of a request

Path parameters

Response

Download cohort

Example: Download a requested cohort

Path parameters

Get usage

Response

Upload cohort

Example: Create a new cohort

Body parameters

Response

Response errors

Upload cohort error response JSON

Update cohort membership

Example: Remove and add cohort members

Request body

Memberships request JSON

Response

Memberships response JSON