> ## 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.

# Search Cohorts

**Tool name** `search_cohorts`

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

Searches for cohorts matching a natural language query across one or more workspaces.

## Example prompt

> Find cohorts of high-income readers interested in luxury cars and premium lifestyle content.

## Parameters

<ParamField body="limit" type="integer (int32)">
  Maximum number of cohorts to return. Defaults to 20, and is capped at 200.
</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="query" type="string" required>
  The keywords, persona or campaign description to match.
</ParamField>

<ParamField body="workspace_ids" type="string[]" required>
  Workspaces to search across. min 1 item.
</ParamField>

## Returns

<ResponseField name="cohorts" type="CohortSearchResult[]">
  Cohorts matching the query, ranked by relevance (most relevant first).

  <Expandable title="CohortSearchResult">
    <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="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="summary" type="string">
      A summary of how users are targeted in this cohort. May be absent for newly created cohorts.
    </ResponseField>

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