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

# Find Audience Extensions

**Tool name** `find_audience_extensions`

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

Discovers cohorts you have not specified whose users correlate with a seed audience — the cohorts most worth considering as an extension of it, each with its overlap and index (affinity). A discovery tool, not a reporting one.

## Example prompt

> Which cohorts should I add to my luxury car intenders audience to extend its reach, and how many net-new users would each bring?

## Parameters

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

<ParamField body="exclude_cohorts" type="string[]">
  Cohort short ids to exclude from the suggestions, on top of the seed's own cohorts (always excluded).
</ParamField>

<ParamField body="include_low_confidence" type="boolean">
  Include `low` confidence suggestions. Defaults to true.
</ParamField>

<ParamField body="max_overlap" type="number (double)">
  Drop suggestions containing at least this share of the seed (0 to 1). Defaults to 0.9.
</ParamField>

<ParamField body="min_users" type="integer (int64)">
  Only suggest cohorts with at least this many users. Defaults to 1000.
</ParamField>

<ParamField body="optimise_for" type="enum">
  How to trade estimate precision against how long the call takes. Defaults to `balanced`. one of: `accuracy`, `balanced`, `speed`.
</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="restrict_to" type="RestrictTo object">
  Narrow the measured population to activity matching these dimensions.

  <Expandable title="RestrictTo">
    <ParamField body="countries" type="string[]">
      ISO 3166-1 alpha-3 country codes (e.g. GBR, USA). When set, only activity in these countries is counted. Use get\_workspace\_details to find which workspaces have user activities in which countries.
    </ParamField>

    <ParamField body="domains" type="string[]">
      Domain names (e.g. example.co.uk). When set, only activity on these domains is counted. Use the workspace's own domains, from get\_workspace\_details.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="seed_audience" type="string">
  The seed audience to extend, a LISP S-expression over cohort short ids. Required unless you are paging.
</ParamField>

<ParamField body="window" type="Window object">
  The date window to measure over.

  <Expandable title="Window">
    <ParamField body="end" type="string (date)">
      End of the window (inclusive), ISO date e.g. 2026-06-30. Omit to default to today.
    </ParamField>

    <ParamField body="start" type="string (date)">
      Start of the window (inclusive), ISO date e.g. 2026-06-01. Omit to default to 30 days before end.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="workspace_ids" type="string[]" required>
  Workspaces whose user-behaviour data the suggestions are drawn from and measured across. min 1 item.
</ParamField>

## Returns

<ResponseField name="next_page_token" type="string">
  Pass as `page_token` to fetch the next page of suggestions. 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="seed_reach" type="CohortReach object">
  The seed audience's own reach over the window, with any restrict\_to applied. Returned on the first page only.

  <Expandable title="CohortReach">
    <ResponseField name="page_views" type="integer (int64)" required>
      Estimated page views over the measurement window.
    </ResponseField>

    <ResponseField name="users" type="integer (int64)" required>
      Estimated unique users over the measurement window.
    </ResponseField>

    <ResponseField name="video_views" type="integer (int64)" required>
      Estimated video views over the measurement window.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="suggestions" type="AudienceExtension[]">
  A page of up to 50 suggested cohorts to extend the seed audience, ordered by index descending (strongest affinity first). Near-duplicates of the seed (overlap at or above max\_overlap) are excluded, so a high-index cohort that merely re-surfaces the seed doesn't crowd out genuine extensions.

  <Expandable title="AudienceExtension">
    <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_id" type="string" required>
      Short cohort identifier. Pass to get\_cohort\_detail, and as the cohort reference in measure\_audiences expressions.
    </ResponseField>

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

    <ResponseField name="confidence" type="enum" required>
      How reliable this suggestion's index and overlap are — they're estimated from sampled sketches, not exact counts, and the estimate is noisiest when the overlap with the seed is small. Treat `high` as trustworthy; on `medium` and `low`, weigh that the true value may differ substantially, and re-measure with compare\_audience before reporting a figure. All three levels are returned by default; set include\_low\_confidence to false to drop `low`. one of: `high`, `medium`, `low`.
    </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="incremental_reach_percent" type="number (double)" required>
      Those net-new users as a percentage of the seed's own size: `incremental_reach_users` / `seed_reach.users` × 100 — how much adding this cohort would grow the seed audience.
    </ResponseField>

    <ResponseField name="incremental_reach_users" type="integer (int64)" required>
      Net-new users this cohort would add to the seed — users in the cohort but not already in the seed.
    </ResponseField>

    <ResponseField name="index" type="number (double)" required>
      How much more or less likely a cohort member is to be in this cohort than the average user: 1.0 = average, above 1.0 = over-represented.
    </ResponseField>

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

    <ResponseField name="overlap_percent" type="number (double)" required>
      What percentage of the **seed audience** is also in this cohort: `overlap_users` / `seed_reach.users` × 100.
    </ResponseField>

    <ResponseField name="overlap_users" type="integer (int64)" required>
      Users the cohort shares with the seed audience.
    </ResponseField>

    <ResponseField name="owning_workspace" type="string (uuid)">
      Workspace where this cohort was originally defined.
    </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>
      The cohort's own size over the window.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total_matching" type="integer (int32)" required>
  How many suggestions this query returns in total, across all pages — at most 200, the strongest by index.
</ResponseField>

<ResponseField name="unavailable" type="string[]">
  Seed cohorts not available in any of the requested workspaces. Returned on the first page only.
</ResponseField>

<ResponseField name="weak_seed" type="WeakSeed object">
  Present only when no cohort in the library was a usable extension of the seed — the seed overlaps too little to extend from. Returned on the first page only.

  <Expandable title="WeakSeed">
    <ResponseField name="reason" type="string" required>
      Why the seed is considered weak.
    </ResponseField>

    <ResponseField name="suggestions_found" type="integer (int32)" required>
      The number of suggestions found (0 when the seed is too weak to extend from).
    </ResponseField>
  </Expandable>
</ResponseField>