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

integer

required

The ID of the project to retrieve cohorts from

Query Parameters

string

Filter cohorts by type:

static - Only static cohorts (fixed membership)
dynamic - Only dynamic cohorts (auto-updating)

integer

Filter cohorts created by a specific user ID

string

Search cohorts by name (case-insensitive partial match)

boolean

default:false

If true, exclude cohorts with behavioral filters (useful for feature flag selection)

integer

default:100

Maximum number of results to return

integer

default:0

Number of results to skip (for pagination)

Response Fields

array

Array of cohort objects

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 (true) or dynamic (false)

integer

Current number of users in the cohort

boolean

Whether the cohort is currently being recalculated

object

User who created the cohort

string

ISO 8601 timestamp of creation

string

ISO 8601 timestamp of last calculation

string

Type of cohort (e.g., “realtime”)

integer

Number of calculation errors encountered

string

Human-readable error message if calculation failed

integer

Total number of cohorts matching the filters

string

URL for the next page of results (if available)

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"

import posthog

posthog.project_api_key = 'YOUR_API_KEY'

cohorts = posthog.get('/api/projects/12345/cohorts/')

print(f"Found {cohorts['count']} cohorts")
for cohort in cohorts['results']:
    print(f"- {cohort['name']}: {cohort['count']} users")

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

const data = await response.json();
console.log(`Found ${data.count} cohorts`);
data.results.forEach(cohort => {
  console.log(`- ${cohort.name}: ${cohort.count} users`);
});

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"

import posthog

posthog.project_api_key = 'YOUR_API_KEY'

cohorts = posthog.get('/api/projects/12345/cohorts/', params={'type': 'static'})

print(f"Found {len(cohorts['results'])} static cohorts")

const response = await fetch(
  'https://app.posthog.com/api/projects/12345/cohorts/?type=static',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const data = await response.json();
console.log(`Found ${data.results.length} static cohorts`);

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"

import posthog

posthog.project_api_key = 'YOUR_API_KEY'

cohorts = posthog.get('/api/projects/12345/cohorts/', params={'search': 'active'})

for cohort in cohorts['results']:
    print(f"{cohort['name']}: {cohort['count']} users")

const response = await fetch(
  'https://app.posthog.com/api/projects/12345/cohorts/?search=active',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const data = await response.json();
data.results.forEach(cohort => {
  console.log(`${cohort.name}: ${cohort.count} users`);
});

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"

import posthog

posthog.project_api_key = 'YOUR_API_KEY'

# Get second page (10 results per page)
cohorts = posthog.get('/api/projects/12345/cohorts/', params={
    'limit': 10,
    'offset': 10
})

print(f"Showing {len(cohorts['results'])} of {cohorts['count']} total cohorts")

const response = await fetch(
  'https://app.posthog.com/api/projects/12345/cohorts/?limit=10&offset=20',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const data = await response.json();
console.log(`Showing ${data.results.length} of ${data.count} total cohorts`);

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": "user@example.com",
        "first_name": "Jane",
        "email": "jane@example.com"
      },
      "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": "user@example.com",
        "first_name": "Jane",
        "email": "jane@example.com"
      },
      "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

error

Invalid or missing API key

error

Insufficient permissions to view cohorts

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

Overview

Events

Feature Flags

Cohorts

Insights

List Cohorts

List Cohorts

Endpoint

Path Parameters

Query Parameters

Response Fields

Examples

List All Cohorts

Filter Static Cohorts

Search Cohorts

Paginate Results

Response

Error Responses

Notes

​List Cohorts

​Endpoint

​Path Parameters

​Query Parameters

​Response Fields

​Examples

​List All Cohorts

​Filter Static Cohorts

​Search Cohorts

​Paginate Results

​Response

​Error Responses

​Notes

List Cohorts

Endpoint

Path Parameters

Query Parameters

Response Fields

Examples

List All Cohorts

Filter Static Cohorts

Search Cohorts

Paginate Results

Response

Error Responses

Notes