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.