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

# List Cohorts

**Tool name** `list_cohorts`

<Info>Read-only · Idempotent</Info>

Browses the cohorts available across one or more workspaces, filtered by type, state, tags, a name keyword, and a user-count range, and ordered by short id, name, or user count. Each returned cohort includes its estimated unique users over the last 30 days. Returns one page at a time.

## Example prompt

> List all the enabled lookalike cohorts available across my workspaces.

## Parameters

<ParamField body="cohort_types" type="enum[]">
  Restrict to these cohort types. Omit to list all types the caller can see. min 1 item. each one of: `custom`, `lookalike`, `contextual`, `standard`, `classificationModel`, `advertiser`.
</ParamField>

<ParamField body="max_users" type="integer (int64)">
  Only include cohorts with at most this many users. Omit for no upper bound.
</ParamField>

<ParamField body="min_users" type="integer (int64)">
  Only include cohorts with at least this many users. Omit for no lower bound.
</ParamField>

<ParamField body="name_contains" type="string">
  Case-insensitive substring matched against each cohort's name. Omit to match all cohorts.
</ParamField>

<ParamField body="page_token" type="string">
  Opaque token from a previous response's `next_page_token`, to fetch the next page.
</ParamField>

<ParamField body="sort_by" type="enum">
  Field to order the listing by. Defaults to short\_id. one of: `short_id`, `name`, `users`.
</ParamField>

<ParamField body="sort_order" type="enum">
  Order direction. Defaults to ascending. one of: `asc`, `desc`.
</ParamField>

<ParamField body="state" type="enum">
  Restrict to enabled or disabled cohorts. Omit to list both. one of: `enabled`, `disabled`.
</ParamField>

<ParamField body="tags" type="string[]">
  Restrict to cohorts tagged with at least one of these tags. min 1 item.
</ParamField>

<ParamField body="workspace_ids" type="string[]" required>
  Workspaces whose cohorts are aggregated into a single flat list, not broken down by workspace. min 1 item.
</ParamField>

## Returns

<ResponseField name="cohorts" type="CohortListItem[]">
  A page of cohorts matching the query, in the requested order (short id by default).

  <Expandable title="CohortListItem">
    <ResponseField name="available_in_workspaces" type="string[]" required>
      Which of the requested workspaces this cohort can be used from. Pass any of these to follow-up tools. min 1 item.
    </ResponseField>

    <ResponseField name="cohort_type" type="enum" required>
      Cohort type one of: `custom`, `lookalike`, `contextual`, `standard`, `classificationModel`, `advertiser`.
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Human-readable cohort name.
    </ResponseField>

    <ResponseField name="owning_workspace" type="string (uuid)" required>
      Workspace where this cohort was originally defined.
    </ResponseField>

    <ResponseField name="public_id" type="string (uuid)" required>
      Stable unique cohort identifier (UUID).
    </ResponseField>

    <ResponseField name="short_id" type="string" required>
      Short cohort identifier. Pass to get\_cohort\_detail, and as the cohort reference in measure\_audiences expressions.
    </ResponseField>

    <ResponseField name="state" type="string" required>
      Whether the cohort is enabled or disabled.
    </ResponseField>

    <ResponseField name="tags" type="string[]" />

    <ResponseField name="users" type="integer (int64)" required>
      Estimated unique users in the last 30 days, across the requested workspaces.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="incomplete" type="boolean" required>
  True when the listing was capped and some matching cohorts are missing (from this page and every other page of this query).
</ResponseField>

<ResponseField name="next_page_token" type="string">
  Pass as `page_token` to fetch the next page. Absent on the last page. Expires shortly after the first page.
</ResponseField>

<ResponseField name="total_matching" type="integer (int32)" required>
  Total cohorts matching the filters across all pages, before pagination.
</ResponseField>