Skip to main content

​
Create Cohort

Create a new cohort (user segment) in your project. Cohorts can be static (fixed list of users) or dynamic (automatically updated based on filters).

​
Endpoint

POST /api/projects/:project_id/cohorts/

​
Path Parameters

​
project_id
integer
required
The ID of the project to create the cohort in

​
Request Body

​
name
string
required
Name of the cohort (e.g., “Active Users”, “Power Users”)
​
description
string
Optional description explaining what this cohort represents
​
is_static
boolean
default:false
Whether this is a static cohort (fixed list) or dynamic (auto-updating based on filters)
​
filters
object
Filter criteria for dynamic cohorts. Must contain a properties key with filter groups.Example structure:
{
  "properties": {
    "type": "AND",
    "values": [
      {
        "type": "person",
        "key": "email",
        "operator": "is_set",
        "value": null
      }
    ]
  }
}
​
query
object
HogQL query for creating static cohorts from query results. Must be either ActorsQuery or HogQLQuery type.
​
groups
array
Legacy filter format (deprecated). Use filters instead.
​
csv
file
CSV file to upload for static cohorts. File should contain person IDs, distinct IDs, or email addresses.Supported column headers:
  • person_id, person-id, or Person .id
  • distinct_id or distinct-id
  • email or e-mail

​
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 the cohort membership
​
is_static
boolean
Whether this cohort is static (true) or dynamic (false)
​
count
integer
Number of users currently in the cohort
​
is_calculating
boolean
Whether the cohort is currently being calculated
​
created_by
object
User who created the cohort
​
created_at
string
ISO 8601 timestamp of when the cohort was created
​
last_calculation
string
ISO 8601 timestamp of the last time the cohort was calculated
​
cohort_type
string
Type of cohort (e.g., “realtime” for real-time evaluation)

​
Examples

​
Create Dynamic Cohort

Create a cohort of users who have an email address set: 
curl -X POST https://app.posthog.com/api/projects/12345/cohorts/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Users with Email",
    "description": "All users who have provided an email address",
    "is_static": false,
    "filters": {
      "properties": {
        "type": "AND",
        "values": [
          {
            "type": "person",
            "key": "email",
            "operator": "is_set"
          }
        ]
      }
    }
  }'

​
Create Static Cohort

Create a static cohort by uploading a CSV file: 
curl -X POST https://app.posthog.com/api/projects/12345/cohorts/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "name=VIP Customers" \
  -F "description=Our most valuable customers" \
  -F "is_static=true" \
  -F "[email protected]"

​
Create Behavioral Cohort

Create a cohort based on user actions (users who completed onboarding): 
curl -X POST https://app.posthog.com/api/projects/12345/cohorts/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Completed Onboarding",
    "description": "Users who finished the onboarding flow",
    "is_static": false,
    "filters": {
      "properties": {
        "type": "AND",
        "values": [
          {
            "type": "behavioral",
            "key": "onboarding_complete",
            "value": "performed_event",
            "event_type": "events",
            "time_value": 30,
            "time_interval": "day"
          }
        ]
      }
    }
  }'

​
Response

{
  "id": 789,
  "name": "Users with Email",
  "description": "All users who have provided an email address",
  "filters": {
    "properties": {
      "type": "AND",
      "values": [
        {
          "type": "person",
          "key": "email",
          "operator": "is_set"
        }
      ]
    }
  },
  "is_static": false,
  "count": 0,
  "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-15T10:30:00Z",
  "last_calculation": null,
  "errors_calculating": 0,
  "deleted": false,
  "cohort_type": "realtime",
  "version": null,
  "pending_version": 1
}

​
Error Responses

​
400 Bad Request
error
Invalid request body or missing required fields
{
  "type": "validation_error",
  "detail": "Must contain a 'properties' key with type and values"
}
​
401 Unauthorized
error
Invalid or missing API key
​
403 Forbidden
error
Insufficient permissions to create cohorts

​
Notes

  • Dynamic cohorts are recalculated periodically to keep membership up to date
  • Static cohorts have fixed membership unless manually updated
  • Behavioral filters cannot be used in cohorts that are referenced by feature flags
  • CSV uploads support person IDs, distinct IDs, and email addresses
  • Large cohorts may take time to calculate; check is_calculating status
  • Real-time cohorts (for feature flags) have a maximum size limit

Build docs developers (and LLMs) love

Get started for freeTalk to us