> ## 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, subject entity, a name keyword, and a user-count range, and ordered by short id, name, user count, or creation time. Each returned cohort includes its state, tags, subject entity, creation time, and 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. Not every type is available to every caller — filtering on a type the caller can't see returns no cohorts for it, indistinguishable from there being none, so an empty result for a given type may mean it's unavailable rather than absent. min 1 item. each one of: `custom`, `lookalike`, `contextual`, `standard`, `classificationModel`, `advertiser`, `curated`.
</ParamField>

<ParamField body="max_users" type="integer (int64)">
  Only include cohorts with at most this many users. Omit for no upper bound. Filters on `users`, which is measured over the requested workspaces, so which cohorts pass is relative to workspace\_ids: a cohort empty in one workspace may have users across several, so widening the workspace set can move a cohort out of a max\_users result.
</ParamField>

<ParamField body="min_users" type="integer (int64)">
  Only include cohorts with at least this many users. Omit for no lower bound. Filters on `users`, which is measured over the requested workspaces, so which cohorts pass is relative to workspace\_ids: a cohort empty in one workspace may have users across several, so widening the workspace set can move a cohort into a min\_users result.
</ParamField>

<ParamField body="name_contains" type="string">
  Case-insensitive substring matched against each cohort's name. Omit to match all cohorts. If you wish to find cohorts by theme, use search\_cohorts instead; this is a literal substring match, not a semantic search.
</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`, `created_at`.
</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="subject_entity" type="enum">
  Restrict to cohorts describing this kind of thing (a user, group of users, or piece of content). Omit to list all. one of: `user`, `user_group`, `content`.
</ParamField>

<ParamField body="tags" type="string[]">
  Restrict to cohorts tagged with at least one of these tags (case-sensitive, exact match). 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`, `curated`.
    </ResponseField>

    <ResponseField name="created_at" type="string (date-time)">
      When the cohort was created (ISO-8601). Absent for cohort types that don't record a creation time (e.g. standard cohorts).
    </ResponseField>

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

    <ResponseField name="owning_workspace" type="string (uuid)">
      Workspace where this cohort was originally defined.
    </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="subject_entity" type="enum" required>
      What the cohort targets: a user, a group of users (ie. a household), or a piece of content. one of: `user`, `user_group`, `content`.
    </ResponseField>

    <ResponseField name="tags" type="string[]">
      Tags applied to the cohort. Empty when the cohort has none.
    </ResponseField>

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

<ResponseField name="next_page_token" type="string">
  Pass as `page_token` to fetch the next page. Absent on the last page. Valid for about 15 minutes from the first page, so other tool calls in between are fine.
</ResponseField>

<ResponseField name="total_matching" type="integer (int32)" required>
  Total cohorts matching the filters across all pages, before pagination. When a user-count filter (min\_users/max\_users) is set, this total is relative to the requested workspace\_ids (because `users` is measured over that set), so it is not comparable across calls with different workspace sets — a filtered total over more workspaces can be smaller than over one.
</ResponseField>