> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/mixpanel/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Cohorts

> List and query user cohorts

# Query Cohorts

List saved cohorts and retrieve cohort membership information.

## List Saved Cohorts

<ParamField query="project_id" type="integer" required>
  Your Mixpanel project ID
</ParamField>

<ParamField query="workspace_id" type="integer">
  The workspace ID
</ParamField>

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://mixpanel.com/api/query/cohorts/list?project_id=123" \
    -X POST \
    -u SERVICE_ACCOUNT_USERNAME:SERVICE_ACCOUNT_SECRET
  ```

  ```python Python theme={null}
  import requests
  from requests.auth import HTTPBasicAuth

  response = requests.post(
      'https://mixpanel.com/api/query/cohorts/list',
      auth=HTTPBasicAuth('SERVICE_ACCOUNT_USERNAME', 'SERVICE_ACCOUNT_SECRET'),
      params={'project_id': 123}
  )

  cohorts = response.json()
  for cohort in cohorts:
      print(f"{cohort['name']}: {cohort['count']} users")
  ```
</CodeGroup>

### Response

<ResponseField name="count" type="integer">
  Number of users currently in the cohort
</ResponseField>

<ResponseField name="is_visible" type="integer">
  Visibility status (0 = not visible, 1 = visible)
</ResponseField>

<ResponseField name="description" type="string">
  Cohort description
</ResponseField>

<ResponseField name="created" type="string">
  Creation timestamp
</ResponseField>

<ResponseField name="project_id" type="integer">
  Project ID
</ResponseField>

<ResponseField name="id" type="integer">
  Cohort ID
</ResponseField>

<ResponseField name="name" type="string">
  Cohort name
</ResponseField>

<CodeGroup>
  ```json 200 Success theme={null}
  [
    {
      "count": 150,
      "is_visible": 1,
      "description": "Power users who logged in 10+ times",
      "created": "2024-01-15 10:30:00",
      "project_id": 123,
      "id": 1000,
      "name": "Power Users"
    },
    {
      "count": 2500,
      "is_visible": 1,
      "description": "Users who signed up in January",
      "created": "2024-01-01 09:00:00",
      "project_id": 123,
      "id": 1001,
      "name": "January Signups"
    }
  ]
  ```
</CodeGroup>

## Query Cohort Members

Use the `/engage` endpoint with `filter_by_cohort` parameter to get users in a cohort:

<CodeGroup>
  ```python Python theme={null}
  import requests
  from requests.auth import HTTPBasicAuth

  response = requests.post(
      'https://mixpanel.com/api/query/engage',
      auth=HTTPBasicAuth('USERNAME', 'SECRET'),
      params={'project_id': 123},
      data={
          'filter_by_cohort': '{"id": 1000}'
      }
  )

  users = response.json()
  print(f"Total users: {users['total']}")
  for user in users['results']:
      print(f"User: {user['$distinct_id']}")
  ```
</CodeGroup>

See the [Engage documentation](/api-reference/query/engage) for more details on querying profiles.