Update Cohort

Update an existing cohort in your project. You can modify the name, description, filters, or membership for both static and dynamic cohorts.

Endpoint

PATCH /api/projects/:project_id/cohorts/:id/

Path Parameters

integer

required

The ID of the project containing the cohort

integer

required

The ID of the cohort to update

Request Body

All fields are optional. Only include fields you want to update.

string

New name for the cohort

string

New description for the cohort

object

Updated filter criteria for dynamic cohorts. Must contain a properties key.Note: Updating filters triggers recalculation of the cohort.

object

Updated HogQL query for static cohorts created from queries

boolean

Set to true to soft-delete the cohort, or false to restore a deleted cohortNote: Cohorts used in active feature flags, insights, or other cohorts cannot be deleted.

file

CSV file to update membership of static cohorts. This replaces existing members.

Response Fields

integer

Unique identifier for the cohort

string

Name of the cohort

string

Description of the cohort

object

Filter criteria defining cohort membership

boolean

Whether this cohort is static or dynamic

integer

Number of users currently in the cohort

boolean

Whether the cohort is being recalculated

string

ISO 8601 timestamp of last calculation

integer

Version number of the cohort (increments on each update)

Examples

Update Cohort Name

Change the name and description of a cohort:

curl -X PATCH https://app.posthog.com/api/projects/12345/cohorts/789/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Super Active Users",
    "description": "Users with high engagement levels"
  }'

import posthog

posthog.project_api_key = 'YOUR_API_KEY'

cohort = posthog.patch('/api/projects/12345/cohorts/789/', data={
    'name': 'Super Active Users',
    'description': 'Users with high engagement levels'
})

print(f"Updated cohort: {cohort['name']}")

const response = await fetch('https://app.posthog.com/api/projects/12345/cohorts/789/', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Super Active Users',
    description: 'Users with high engagement levels'
  })
});

const cohort = await response.json();
console.log(`Updated cohort: ${cohort.name}`);

Update Cohort Filters

Modify the filter criteria for a dynamic cohort:

curl -X PATCH https://app.posthog.com/api/projects/12345/cohorts/789/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "properties": {
        "type": "AND",
        "values": [
          {
            "type": "person",
            "key": "plan",
            "operator": "exact",
            "value": ["enterprise"]
          },
          {
            "type": "behavioral",
            "key": "login",
            "value": "performed_event",
            "event_type": "events",
            "time_value": 7,
            "time_interval": "day",
            "operator": "gte",
            "operator_value": 5
          }
        ]
      }
    }
  }'

import posthog

posthog.project_api_key = 'YOUR_API_KEY'

cohort = posthog.patch('/api/projects/12345/cohorts/789/', data={
    'filters': {
        'properties': {
            'type': 'AND',
            'values': [
                {
                    'type': 'person',
                    'key': 'plan',
                    'operator': 'exact',
                    'value': ['enterprise']
                },
                {
                    'type': 'behavioral',
                    'key': 'login',
                    'value': 'performed_event',
                    'event_type': 'events',
                    'time_value': 7,
                    'time_interval': 'day',
                    'operator': 'gte',
                    'operator_value': 5
                }
            ]
        }
    }
})

print(f"Cohort is recalculating: {cohort['is_calculating']}")

const response = await fetch('https://app.posthog.com/api/projects/12345/cohorts/789/', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    filters: {
      properties: {
        type: 'AND',
        values: [
          {
            type: 'person',
            key: 'plan',
            operator: 'exact',
            value: ['enterprise']
          },
          {
            type: 'behavioral',
            key: 'login',
            value: 'performed_event',
            event_type: 'events',
            time_value: 7,
            time_interval: 'day',
            operator: 'gte',
            operator_value: 5
          }
        ]
      }
    }
  })
});

const cohort = await response.json();
console.log(`Cohort is recalculating: ${cohort.is_calculating}`);

Update Static Cohort via CSV

Replace the members of a static cohort:

curl -X PATCH https://app.posthog.com/api/projects/12345/cohorts/789/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "csv=@updated_members.csv"

import posthog
import requests

files = {'csv': open('updated_members.csv', 'rb')}

response = requests.patch(
    'https://app.posthog.com/api/projects/12345/cohorts/789/',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    files=files
)

cohort = response.json()
print(f"Cohort updated, new count: {cohort['count']}")

const formData = new FormData();
formData.append('csv', fileInput.files[0]);

const response = await fetch('https://app.posthog.com/api/projects/12345/cohorts/789/', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: formData
});

const cohort = await response.json();
console.log(`Cohort updated, new count: ${cohort.count}`);

Delete a Cohort

Soft-delete a cohort:

curl -X PATCH https://app.posthog.com/api/projects/12345/cohorts/789/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"deleted": true}'

import posthog

posthog.project_api_key = 'YOUR_API_KEY'

cohort = posthog.patch('/api/projects/12345/cohorts/789/', data={'deleted': True})

print(f"Cohort deleted: {cohort['deleted']}")

const response = await fetch('https://app.posthog.com/api/projects/12345/cohorts/789/', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ deleted: true })
});

const cohort = await response.json();
console.log(`Cohort deleted: ${cohort.deleted}`);

Response

{
  "id": 789,
  "name": "Super Active Users",
  "description": "Users with high engagement levels",
  "filters": {
    "properties": {
      "type": "AND",
      "values": [
        {
          "type": "person",
          "key": "plan",
          "operator": "exact",
          "value": ["enterprise"]
        }
      ]
    }
  },
  "is_static": false,
  "count": 245,
  "is_calculating": true,
  "created_by": {
    "id": 123,
    "uuid": "01234567-89ab-cdef-0123-456789abcdef",
    "distinct_id": "user@example.com",
    "first_name": "Jane",
    "email": "jane@example.com"
  },
  "created_at": "2024-01-10T09:00:00Z",
  "last_calculation": "2024-01-15T10:30:00Z",
  "errors_calculating": 0,
  "last_error_message": null,
  "deleted": false,
  "cohort_type": "realtime",
  "version": 4,
  "pending_version": 5
}

Error Responses

error

Invalid request body or validation errorExamples:

{
  "detail": "This cohort is used in 2 active feature flag(s): feature-a, feature-b. Please remove the cohort from these feature flags before deleting it."
}

{
  "detail": "Behavioral filters cannot be added to cohorts used in feature flags.",
  "code": "behavioral_cohort_found"
}

{
  "detail": "Cohorts cannot reference other cohorts in a loop."
}

error

Invalid or missing API key

error

Insufficient permissions to update cohorts

error

Cohort not found

Notes

Updating filters on a dynamic cohort triggers automatic recalculation
You cannot delete cohorts that are:
- Used in active feature flags
- Referenced in other cohorts
- Used in insights
- Used in test account filters
Behavioral filters cannot be added to cohorts used in feature flags
Cohorts cannot form circular dependencies (cohort A referencing cohort B which references cohort A)
Updating a static cohort via CSV replaces all existing members
The version field increments with each update
Set deleted: false to restore a previously deleted cohort

Overview

Events

Feature Flags

Cohorts

Insights

Update Cohort

Update Cohort

Endpoint

Path Parameters

Request Body

Response Fields

Examples

Update Cohort Name

Update Cohort Filters

Update Static Cohort via CSV

Delete a Cohort

Response

Error Responses

Notes

​Update Cohort

​Endpoint

​Path Parameters

​Request Body

​Response Fields

​Examples

​Update Cohort Name

​Update Cohort Filters

​Update Static Cohort via CSV

​Delete a Cohort

​Response

​Error Responses

​Notes

Update Cohort

Endpoint

Path Parameters

Request Body

Response Fields

Examples

Update Cohort Name

Update Cohort Filters

Update Static Cohort via CSV

Delete a Cohort

Response

Error Responses

Notes