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

# Compare Audience

**Tool name** `compare_audience`

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

Measures how a set of cohorts you specify relate to an audience: for each cohort, its overlap with the audience, its index — how much more or less likely a cohort member is to be in it than the average user — and how many net-new users it would add. Use this to get precise numbers on how cohorts are related to each other.

## Example prompt

> Which of my sports cohorts over-index against my luxury car intenders audience, and by how much?

## Parameters

<ParamField body="audience" type="string" required>
  The audience to compare against, a LISP S-expression over cohort short ids.
</ParamField>

<ParamField body="comparison_cohorts" type="string[]" required>
  The cohorts to compare the audience against — their short ids. min 1 item.
</ParamField>

<ParamField body="optimise_for" type="enum">
  How to trade estimate precision against how long the call takes. Omit for `accuracy`, which is the right choice here: this tool exists to produce figures you can report. one of: `accuracy`, `balanced`, `speed`.
</ParamField>

<ParamField body="restrict_to" type="RestrictTo object">
  Narrow the compared 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="window" type="Window object">
  The date window to compare 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 is compared across. min 1 item.
</ParamField>

## Returns

<ResponseField name="audience_reach" type="CohortReach object" required>
  The audience's own reach over the window, with any restrict\_to applied — the denominator behind every comparison's `overlap_percent` and `incremental_reach_percent`.

  <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="comparisons" type="AudienceComparison[]">
  One entry per comparison cohort available in the requested workspaces, in the order you supplied them.

  <Expandable title="AudienceComparison">
    <ResponseField name="cohort_id" type="string" required>
      The comparison cohort's short id.
    </ResponseField>

    <ResponseField name="incremental_reach_percent" type="number (double)" required>
      Those net-new users as a percentage of the audience's own size: `incremental_reach_users` / `audience_reach.users` × 100 — how much adding this cohort would grow the audience.
    </ResponseField>

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

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

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

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

    <ResponseField name="users" type="integer (int64)" required>
      The cohort's own size over the window.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="unavailable" type="string[]">
  Comparison cohorts (or cohorts referenced by the audience) not available in any of the requested workspaces.
</ResponseField>