The Amplitude Behavioral Cohorts API allows developers to list, export, and upload cohorts in Amplitude. Cohorts are groups of users defined by shared behavioral patterns or properties. This API supports downloading cohort membership lists, creating new cohorts from external data, and retrieving cohort metadata. It is commonly used for syncing audience segments with marketing platforms, CRMs, and other downstream tools.
openapi: 3.1.0
info:
title: Amplitude Behavioral Cohorts API
description: >-
The Amplitude Behavioral Cohorts API allows developers to list, export,
and upload cohorts in Amplitude. Cohorts are groups of users defined by
shared behavioral patterns or properties. This API supports downloading
cohort membership lists, creating new cohorts from external data, and
retrieving cohort metadata. It is commonly used for syncing audience
segments with marketing platforms, CRMs, and other downstream tools.
version: '3'
contact:
name: Amplitude Support
url: https://amplitude.com/contact
termsOfService: https://amplitude.com/terms
externalDocs:
description: Amplitude Behavioral Cohorts API Documentation
url: https://amplitude.com/docs/apis/analytics/behavioral-cohorts
servers:
- url: https://amplitude.com
description: Amplitude Production Server
tags:
- name: Cohorts
description: Cohort management and export operations
security:
- basicAuth: []
paths:
/api/3/cohorts:
get:
operationId: listCohorts
summary: Amplitude List All Cohorts
description: >-
Retrieve a list of all cohorts in the project including their
metadata such as name, description, size, and last computed date.
tags:
- Cohorts
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/CohortListResponse'
examples:
listCohorts200Example:
summary: Default listCohorts 200 response
x-microcks-default: true
value:
cohorts:
- example_value
'401':
description: Unauthorized
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/5/cohorts/request/{cohort_id}:
get:
operationId: requestCohortExport
summary: Amplitude Request a Cohort Export
description: >-
Request an asynchronous export of a specific cohort. This is the first
step in a three-step process to download cohort membership data. After
requesting, poll the status endpoint, then download the file when ready.
tags:
- Cohorts
parameters:
- name: cohort_id
in: path
required: true
description: >-
The ID of the cohort to export.
schema:
type: string
- name: props
in: query
description: >-
Set to 1 to include user properties in the export.
schema:
type: integer
enum:
- 0
- 1
responses:
'200':
description: Success - export request accepted
content:
application/json:
schema:
$ref: '#/components/schemas/CohortRequestResponse'
examples:
requestCohortExport200Example:
summary: Default requestCohortExport 200 response
x-microcks-default: true
value:
request_id: '500123'
cohort_id: '500123'
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: Cohort not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/5/cohorts/request/{cohort_id}/status:
get:
operationId: getCohortExportStatus
summary: Amplitude Get Cohort Export Status
description: >-
Poll the status of a previously requested cohort export. Returns the
current state of the export job. Continue polling until the status
indicates the export is complete.
tags:
- Cohorts
parameters:
- name: cohort_id
in: path
required: true
description: >-
The ID of the cohort whose export status to check.
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/CohortStatusResponse'
examples:
getCohortExportStatus200Example:
summary: Default getCohortExportStatus 200 response
x-microcks-default: true
value:
request_id: '500123'
status: queued
'401':
description: Unauthorized
'404':
description: Cohort not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/5/cohorts/request/{cohort_id}/file:
get:
operationId: downloadCohortExport
summary: Amplitude Download Cohort Export File
description: >-
Download the exported cohort membership data file. This endpoint should
only be called after the export status indicates completion.
tags:
- Cohorts
parameters:
- name: cohort_id
in: path
required: true
description: >-
The ID of the cohort to download.
schema:
type: string
responses:
'200':
description: Success - returns the cohort data file
content:
application/json:
schema:
type: object
description: >-
Cohort membership data including user IDs and optional
properties.
examples:
downloadCohortExport200Example:
summary: Default downloadCohortExport 200 response
x-microcks-default: true
value: {}
'401':
description: Unauthorized
'404':
description: Cohort not found or export not ready
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/3/cohorts/upload:
post:
operationId: uploadCohort
summary: Amplitude Upload a Cohort
description: >-
Create or update a cohort by uploading a list of user IDs or Amplitude
IDs. This allows importing audience segments from external systems
into Amplitude for analysis and targeting.
tags:
- Cohorts
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CohortUploadRequest'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/CohortUploadResponse'
examples:
uploadCohort200Example:
summary: Default uploadCohort 200 response
x-microcks-default: true
value:
cohort_id: '500123'
'400':
description: Bad request - invalid cohort data
'401':
description: Unauthorized
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
Use your Amplitude API key as the username and your secret key as the
password. Encode them as base64 in the format api_key:secret_key.
schemas:
CohortListResponse:
type: object
properties:
cohorts:
type: array
description: >-
Array of cohort metadata objects.
items:
$ref: '#/components/schemas/Cohort'
Cohort:
type: object
properties:
id:
type: string
description: >-
The unique identifier for the cohort.
name:
type: string
description: >-
The name of the cohort.
description:
type: string
description: >-
A description of the cohort.
size:
type: integer
description: >-
The number of users in the cohort.
lastComputed:
type: string
format: date-time
description: >-
The date and time the cohort was last computed.
archived:
type: boolean
description: >-
Whether the cohort is archived.
owner:
type: string
description: >-
The email of the cohort owner.
appId:
type: integer
description: >-
The Amplitude project ID the cohort belongs to.
CohortRequestResponse:
type: object
properties:
request_id:
type: string
description: >-
The ID of the export request for polling status.
cohort_id:
type: string
description: >-
The ID of the cohort being exported.
CohortStatusResponse:
type: object
properties:
request_id:
type: string
description: >-
The ID of the export request.
status:
type: string
description: >-
The status of the export job.
enum:
- queued
- computing
- complete
- failed
CohortUploadRequest:
type: object
required:
- name
- ids
properties:
name:
type: string
description: >-
The name of the cohort to create or update.
ids:
type: array
description: >-
Array of user_id or amplitude_id values to include in the cohort.
items:
type: string
owner:
type: string
description: >-
The email address of the cohort owner.
existing_cohort_id:
type: string
description: >-
If provided, updates the existing cohort with this ID instead of
creating a new one.
CohortUploadResponse:
type: object
properties:
cohort_id:
type: string
description: >-
The ID of the created or updated cohort.