## 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`. | Data residency | Base URL | | -------------- | ------------------------------------ | | Default | `https://amplitude.com` | | EU | `https://analytics.eu.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](#get-one-cohort) request counts toward this limit. Use the [Get usage](#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](/docs/data/destination-catalog/amazon-kinesis-cohort) - Create a cohort sync to a custom destination with a [Webhook](/docs/data/destination-catalog/cohort-webhooks) - Create a cohort sync to [Profile API](/docs/apis/analytics/user-profile#get-cohort-ids) - 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. {% code-group %} ```curl cURL curl --location --request GET 'https://amplitude.com/api/3/cohorts' \ -u '{api_key}:{secret_key}' ``` ```bash HTTP GET /api/3/cohorts HTTP/1.1 Host: amplitude.com Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded ``` {% /code-group %} ### 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. {% code-group %} ```curl cURL curl --location --request GET 'https://amplitude.com/api/5/cohorts/request/id' -u '{api_key}:{secret_key}' ``` ```bash HTTP GET /api/5/cohorts/request/id HTTP/1.1 Host: amplitude.com Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded ``` {% /code-group %} {% accordion title="Example: Get a cohort with specific properties" %} This example gets the cohort with ID `26umsb5` and includes the properties `Property1` and `Property2`. {% code-group %} ```curl cURL curl --location --request GET 'https://amplitude.com/api/5/cohorts/request/26umsb5?props=1&propKeys=Property1&propKeys=Property2' --header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' ``` ```bash HTTP GET /api/5/cohorts/request/26umsb5?props=1&propKeys=Property1&propKeys=Property2 HTTP/1.1 Host: amplitude.com Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA= ``` {% /code-group %} {% /accordion %} {% accordion title="Example: Get cohort with all properties" %} {% code-group %} ```curl cURL curl --location --request GET 'https://amplitude.com/api/5/cohorts/request/26umsb5?props=1' --header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' ``` ```bash HTTP GET /api/5/cohorts/request/26umsb5?props=1 HTTP/1.1 Host: amplitude.com Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA= ``` {% /code-group %} {% /accordion %} ### 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": "", "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. {% code-group %} ```curl cURL curl --location --request GET 'https://amplitude.com/api/5/cohorts/request-status/:request_id' \ -u '{api_key}:{secret_key}'' ``` ```bash HTTP GET /api/5/cohorts/request-status/:request_id HTTP/1.1 Host: amplitude.com Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded ``` {% /code-group %} {% accordion title="Example: Get the status of a request" %} This example gets the status of request with the ID `qfaZya`. {% code-group %} ```curl cURL curl --location --request GET 'https://amplitude.com/api/5/cohorts/request-status/qfaZya' \ --header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' ``` ```bash HTTP GET /api/5/cohorts/request-status/qfaZya HTTP/1.1 Host: amplitude.com Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA= ``` {% /code-group %} {% /accordion %} ### Path parameters | Name | Description | | ------------ | -------------------------------------------------------------------------------------- | | `request_id` | Required. The request ID retrieved with the [get one cohort](#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": "", "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": "", "cohort_id": "", "async_status": "JOB COMPLETED" } ``` ## Download cohort After the job finishes running, download the cohort. The following is a basic request. {% code-group %} ```curl cURL curl --location --request GET 'https://amplitude.com/api/5/cohorts/request/:requestId/file' \ -u '{api_key}:{secret_key}' ``` ```bash HTTP GET /api/5/cohorts/request/requestId/file HTTP/1.1 Host: amplitude.com Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded ``` {% /code-group %} {% accordion title="Example: Download a requested cohort" %} This request downloads the file for request ID `Sf7M9j`. {% code-group %} ```curl cURL curl --location --request GET 'https://amplitude.com/api/5/cohorts/request/Sf7M9j/file' --header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' ``` ```bash HTTP GET /api/5/cohorts/request/Sf7M9j/file HTTP/1.1 Host: amplitude.com Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA= ``` {% /code-group %} {% /accordion %} ### Path parameters | Name | Description | | ------------ | -------------------------------------------------------------------------------------- | | `request_id` | Required. The request ID retrieved with the [get one cohort](#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. {% code-group %} ```curl cURL curl --location --request GET 'https://amplitude.com/api/3/cohorts/usage' \ -u '{api_key}:{secret_key}' ``` ```bash HTTP GET /api/3/cohorts/usage HTTP/1.1 Host: amplitude.com Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded ``` {% /code-group %} ### 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. {% code-group %} ```bash cURL 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 }' ``` ```bash HTTP POST /api/3/cohorts/upload HTTP/1.1 Host: amplitude.com Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded Content-Type: application/json Content-Length: 201 { "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 } ``` {% /code-group %} {% accordion title="Example: Create a new cohort" %} This example creates a new cohort named "New Cohort" and includes the Amplitude IDs `10101010101010ID1` and `00000010101010ID2`. {% code-group %} ```bash cURL curl --location --request POST 'https://amplitude.com/api/3/cohorts/upload' \ --header 'Content-Type: application/json' \ --header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' \ -u '{api_key}:{secret_key}' \ --data-raw '{ "name": "New Cohort", "app_id": 153957, "id_type": "BY_AMP_ID", "ids": [ "10101010101010ID1", "00000010101010ID2" ], "owner": "datamonster@amplitude.com", "published": true }' ``` ```bash HTTP POST /api/3/cohorts/upload HTTP/1.1 Host: amplitude.com Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA= Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded Content-Type: application/json Content-Length: 280 { "name": "New Cohort", "app_id": 153957, "id_type": "BY_AMP_ID", "ids": [ "10101010101010ID1", "00000010101010ID2" ], "owner": "datamonster@amplitude.com", "published": true } ``` {% /code-group %} {% /accordion %} ### 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](#upload-cohort-error-response-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. {% code-group %} ```bash cURL 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 } ``` ```bash HTTP POST /api/3/cohorts/membership HTTP/1.1 Host: amplitude.com Content-Type: application/json Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded Content-Length: 362 { "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, } ``` {% /code-group %} {% accordion title="Example: Remove and add cohort members" %} This example adds IDs `111` and `222` by ID, removes IDs `333` and `444` by ID, and removes IDs `asd` and `qwe` by name from the cohort with ID `1a2bc3d`. The operation is set to skip invalid IDs. {% code-group %} ```bash cURL curl --location --request POST 'https://amplitude.com/api/3/cohorts/membership' \ --header 'Content-Type: application/json' \ --header 'Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA=' \ --data-raw '{ "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, }' ``` ```bash HTTP POST /api/3/cohorts/membership HTTP/1.1 Host: amplitude.com Content-Type: application/json Authorization: Basic MTIzNDU2NzgwMDoxMjM0NTY3MDA= Content-Length: 362 { "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, } ``` {% /code-group %} {% /accordion %} ### 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](#memberships-request-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](#memberships-response-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 |