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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.