Skip to main content

​
List Cohorts

Retrieve a list of all cohorts (user segments) in your project. Supports filtering by type, creator, and search term.

​
Endpoint

GET /api/projects/:project_id/cohorts/

​
Path Parameters

​
project_id
integer
required
The ID of the project to retrieve cohorts from

​
Query Parameters

​
type
string
Filter cohorts by type:
  • static - Only static cohorts (fixed membership)
  • dynamic - Only dynamic cohorts (auto-updating)
​
created_by_id
integer
Filter cohorts created by a specific user ID
​
search
string
Search cohorts by name (case-insensitive partial match)
​
hide_behavioral_cohorts
boolean
default:false
If true, exclude cohorts with behavioral filters (useful for feature flag selection)
​
limit
integer
default:100
Maximum number of results to return
​
offset
integer
default:0
Number of results to skip (for pagination)

​
Response Fields

​
results
array
Array of cohort objects
​
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 (true) or dynamic (false)
​
count
integer
Current number of users in the cohort
​
is_calculating
boolean
Whether the cohort is currently being recalculated
​
created_by
object
User who created the cohort
​
created_at
string
ISO 8601 timestamp of creation
​
last_calculation
string
ISO 8601 timestamp of last calculation
​
cohort_type
string
Type of cohort (e.g., “realtime”)
​
errors_calculating
integer
Number of calculation errors encountered
​
last_error_message
string
Human-readable error message if calculation failed
​
count
integer
Total number of cohorts matching the filters
​
next
string
URL for the next page of results (if available)
​
previous
string
URL for the previous page of results (if available)

​
Examples

​
List All Cohorts

Retrieve all cohorts in your project: 
curl -X GET "https://app.posthog.com/api/projects/12345/cohorts/" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Filter Static Cohorts

Retrieve only static cohorts: 
curl -X GET "https://app.posthog.com/api/projects/12345/cohorts/?type=static" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Search Cohorts

Search for cohorts by name: 
curl -X GET "https://app.posthog.com/api/projects/12345/cohorts/?search=active" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Paginate Results

Retrieve cohorts with pagination: 
curl -X GET "https://app.posthog.com/api/projects/12345/cohorts/?limit=10&offset=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

{
  "count": 42,
  "next": "https://app.posthog.com/api/projects/12345/cohorts/?limit=100&offset=100",
  "previous": null,
  "results": [
    {
      "id": 123,
      "name": "Active Users",
      "description": "Users who logged in within the last 7 days",
      "filters": {
        "properties": {
          "type": "AND",
          "values": [
            {
              "type": "behavioral",
              "key": "user_login",
              "value": "performed_event",
              "event_type": "events",
              "time_value": 7,
              "time_interval": "day"
            }
          ]
        }
      },
      "is_static": false,
      "count": 1523,
      "is_calculating": false,
      "created_by": {
        "id": 456,
        "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-15T14:30:00Z",
      "errors_calculating": 0,
      "last_error_message": null,
      "deleted": false,
      "cohort_type": "realtime",
      "version": 3,
      "pending_version": null
    },
    {
      "id": 124,
      "name": "VIP Customers",
      "description": "High-value customers from manual upload",
      "filters": {
        "properties": {
          "type": "AND",
          "values": []
        }
      },
      "is_static": true,
      "count": 89,
      "is_calculating": false,
      "created_by": {
        "id": 456,
        "uuid": "01234567-89ab-cdef-0123-456789abcdef",
        "distinct_id": "[email protected]",
        "first_name": "Jane",
        "email": "[email protected]"
      },
      "created_at": "2024-01-12T11:20:00Z",
      "last_calculation": "2024-01-12T11:21:00Z",
      "errors_calculating": 0,
      "last_error_message": null,
      "deleted": false,
      "cohort_type": null,
      "version": 1,
      "pending_version": null
    }
  ]
}

​
Error Responses

​
401 Unauthorized
error
Invalid or missing API key
​
403 Forbidden
error
Insufficient permissions to view cohorts
​
404 Not Found
error
Project not found

​
Notes

  • Results are ordered by creation date (newest first)
  • Deleted cohorts are excluded from results
  • The count field reflects the current number of users, updated during recalculation
  • is_calculating indicates if the cohort is being processed in the background
  • Static cohorts do not recalculate automatically
  • Use hide_behavioral_cohorts=true when selecting cohorts for feature flags

Build docs developers (and LLMs) love

Get started for freeTalk to us