openapi: 3.2.0
info:
  title: Analytics Cohorts API
  version: 1.0.0
  description: To acquire a personal access token go to [Account settings](https://analytics.pypestream.com/me/settings) and create a new token or use an existing one
servers:
- url: https://analytics.pypestream.com/
  description: Production server US
security:
- APIKey: []
tags:
- name: Cohorts
paths:
  /api/datasets/{dataset_id}/cohorts/:
    get:
      description: 'Cohorts: Groups of users defined in Data Management based on shared characteristics (properties) or behaviors (events performed or not performed) within a specific timeframe. Used for targeted analysis and filtering.


        Get a list of cohorts for a specific dataset.

        '
      operationId: cohorts_list
      parameters:
      - in: path
        name: dataset_id
        required: true
        schema:
          type: string
        description: Dataset ID of the dataset you're trying to access. To find the ID of the dataset, make a call to /api/datasets/.
      - name: limit
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - name: offset
        required: false
        in: query
        description: The initial index from which to return the results.
        schema:
          type: integer
      tags:
      - Cohorts
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedCohortList'
          description: ''
  /api/datasets/{dataset_id}/cohorts/{id}/:
    get:
      description: 'Cohorts: Groups of users defined in Data Management based on shared characteristics (properties) or behaviors (events performed or not performed) within a specific timeframe. Used for targeted analysis and filtering.


        Get a specific cohort from a specific dataset.

        '
      operationId: cohorts_retrieve
      parameters:
      - in: path
        name: dataset_id
        required: true
        schema:
          type: string
        description: Dataset ID of the dataset you're trying to access. To find the ID of the dataset, make a call to /api/datasets/.
      - in: path
        name: id
        schema:
          type: integer
        description: A unique integer value identifying this cohort.
        required: true
      tags:
      - Cohorts
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cohort'
          description: ''
  /api/datasets/{dataset_id}/cohorts/{id}/persons/:
    get:
      description: 'Cohorts: Groups of users defined in Data Management based on shared characteristics (properties) or behaviors (events performed or not performed) within a specific timeframe. Used for targeted analysis and filtering.


        Person / Persons: A feature within Data Management representing individual users tracked by Analytics.  The "Persons" list allows accessing detailed profiles for each user, showing their associated properties,  event history, cohort memberships, and related replays.


        Get all persons in a specific cohort from a specific dataset.

        '
      operationId: cohorts_persons_retrieve
      parameters:
      - in: path
        name: dataset_id
        required: true
        schema:
          type: string
        description: Dataset ID of the dataset you're trying to access. To find the ID of the dataset, make a call to /api/datasets/.
      - in: query
        name: format
        schema:
          type: string
          enum:
          - csv
          - json
      - in: path
        name: id
        schema:
          type: integer
        description: A unique integer value identifying this cohort.
        required: true
      tags:
      - Cohorts
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cohort'
            text/csv:
              schema:
                $ref: '#/components/schemas/Cohort'
          description: ''
components:
  schemas:
    PaginatedCohortList:
      type: object
      properties:
        count:
          type: integer
          example: 123
        next:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?offset=400&limit=100
        previous:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?offset=200&limit=100
        results:
          type: array
          items:
            $ref: '#/components/schemas/Cohort'
    UserBasic:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        uuid:
          type: string
          format: uuid
          readOnly: true
        distinct_id:
          type:
          - string
          - 'null'
          maxLength: 200
        first_name:
          type: string
          maxLength: 150
        email:
          type: string
          format: email
          title: Email address
          maxLength: 254
        is_email_verified:
          type:
          - boolean
          - 'null'
      required:
      - email
      - id
      - uuid
    Cohort:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        name:
          type:
          - string
          - 'null'
          maxLength: 400
        description:
          type: string
          maxLength: 1000
        groups:
          type: object
          additionalProperties: {}
        deleted:
          type: boolean
        filters:
          type:
          - object
          - 'null'
          additionalProperties: {}
        is_calculating:
          type: boolean
          readOnly: true
        created_by:
          allOf:
          - $ref: '#/components/schemas/UserBasic'
          readOnly: true
        created_at:
          type:
          - string
          - 'null'
          format: date-time
          readOnly: true
        last_calculation:
          type:
          - string
          - 'null'
          format: date-time
          readOnly: true
        errors_calculating:
          type: integer
          readOnly: true
        count:
          type:
          - integer
          - 'null'
          readOnly: true
        is_static:
          type: boolean
      required:
      - count
      - created_at
      - created_by
      - errors_calculating
      - id
      - is_calculating
      - last_calculation
  securitySchemes:
    APIKey:
      type: http
      scheme: bearer
x-tagGroups:
- name: All endpoints
  tags:
  - Actions
  - Annotations
  - Batch Exports
  - Change
  - Cohorts
  - Dashboards
  - Datasets
  - Domains
  - Event Definitions
  - Events
  - Funnel
  - Insights
  - KPIs
  - Members
  - Organization
  - Persons
  - Projects
  - Property Definitions
  - Query
  - Tags
  - Trend
  - Users
  - Warehouse Table