Skip to main content

​
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

​
project_id
integer
required
The ID of the project containing the cohort
​
id
integer
required
The ID of the cohort to update

​
Request Body

All fields are optional. Only include fields you want to update.
​
name
string
New name for the cohort
​
description
string
New description for the cohort
​
filters
object
Updated filter criteria for dynamic cohorts. Must contain a properties key.Note: Updating filters triggers recalculation of the cohort.
​
query
object
Updated HogQL query for static cohorts created from queries
​
deleted
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.
​
csv
file
CSV file to update membership of static cohorts. This replaces existing members.

​
Response Fields

​
id
integer
Unique identifier for the cohort
​
name
string
Name of the cohort
​
description
string
Description of the cohort
​
filters
object
Filter criteria defining cohort membership
​
is_static
boolean
Whether this cohort is static or dynamic
​
count
integer
Number of users currently in the cohort
​
is_calculating
boolean
Whether the cohort is being recalculated
​
last_calculation
string
ISO 8601 timestamp of last calculation
​
version
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"
  }'

​
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
          }
        ]
      }
    }
  }'

​
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"

​
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}'

​
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": "[email protected]",
    "first_name": "Jane",
    "email": "[email protected]"
  },
  "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

​
400 Bad Request
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."
}
​
401 Unauthorized
error
Invalid or missing API key
​
403 Forbidden
error
Insufficient permissions to update cohorts
​
404 Not Found
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

Build docs developers (and LLMs) love

Get started for freeTalk to us