Behavioral Cohorts API

Regions

The base URL depends on your project's data residency. In all examples on this page, use the default base URL unless your project uses Amplitude's EU data center—in that case use the EU base URL in this table.

Requests go to https://amplitude.com (default) or https://analytics.eu.amplitude.com (EU). The https://analytics.amplitude.com hostname is the Analytics web app (browser UI); use the hosts in this table for REST requests, not analytics.amplitude.com.

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 --location --request GET 'https://amplitude.com/api/3/cohorts' \
-u '{api_key}:{secret_key}'

Query parameters

Response

The response is a JSON object with this schema:

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

Each COHORT_OBJECT returned has this schema:

{
    "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:

{
    "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:

"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 --location --request GET 'https://amplitude.com/api/5/cohorts/request/id'
-u '{api_key}:{secret_key}'

Path parameters

Query parameters

Response

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

{
  "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 --location --request GET 'https://amplitude.com/api/5/cohorts/request-status/:request_id' \
-u '{api_key}:{secret_key}''

Path parameters

Response

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

{
  "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.

{
  "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 --location --request GET 'https://amplitude.com/api/5/cohorts/request/:requestId/file' \
-u '{api_key}:{secret_key}'

Path parameters

• 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 --location --request GET 'https://amplitude.com/api/3/cohorts/usage' \
-u '{api_key}:{secret_key}'

Response

{
  "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.

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

Response

The response is a JSON object with this schema:

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

Response errors

Upload cohort error response JSON

Update cohort membership

Add and remove IDs to update existing cohort membership incrementally.

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

Memberships request JSON

Response

Memberships response JSON