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

# Measure Audiences

**Tool name** `measure_audiences`

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

Measures the reach of an audience by combining multiple cohorts — how many users are in it and how many page views they generate.

## Example prompt

> How many users and page views would I reach if I combined the luxury car cohort with the premium travel cohort, broken down by country?

## Parameters

<ParamField body="expressions" type="string[]" required>
  One or more audience expressions to measure, each a string in LISP S-expression form. min 1 item.
</ParamField>

<ParamField body="include" type="enum[]">
  Which breakdowns to include beyond total reach. each one of: `cohort_contributions`, `domain_breakdown`, `device_breakdown`, `country_breakdown`, `workspace_breakdown`, `engagement`, `time_series_daily`, `time_series_weekly`.
</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.
    </ParamField>

    <ParamField body="domains" type="string[]">
      Domain names (e.g. telegraph.co.uk). When set, only activity on these domains is counted.
    </ParamField>
  </Expandable>
</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 is aggregated across. min 1 item.
</ParamField>

## Returns

<ResponseField name="measurements" type="AudienceMeasurement[]">
  One measurement per measurable expression.

  <Expandable title="AudienceMeasurement">
    <ResponseField name="cohort_contributions" type="CohortContribution[]">
      Per-cohort contribution to this expression.

      <Expandable title="CohortContribution">
        <ResponseField name="cohort_id" type="string" required>
          Cohort short id.
        </ResponseField>

        <ResponseField name="total_users" type="integer (int64)" required>
          Cohort's standalone size within the restrict\_to filters.
        </ResponseField>

        <ResponseField name="unique_users" type="integer (int64)" required>
          Cohort's incremental contribution of unique users to the composed expression.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="country_breakdown" type="CountryBreakdownEntry[]">
      Users per country (ISO 3166-1 alpha-3 code) within this expression's audience.

      <Expandable title="CountryBreakdownEntry">
        <ResponseField name="country" type="string" required>
          ISO 3166-1 alpha-3 country code (e.g. GBR, USA).
        </ResponseField>

        <ResponseField name="page_views" type="integer (int64)" required>
          Estimated page views in this country.
        </ResponseField>

        <ResponseField name="users" type="integer (int64)" required>
          Estimated unique users in this country.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="device_breakdown" type="DeviceBreakdownEntry[]">
      Users per device type within this expression's audience.

      <Expandable title="DeviceBreakdownEntry">
        <ResponseField name="device" type="string" required>
          Device type (e.g. Desktop, Mobile, Tablet, CTV).
        </ResponseField>

        <ResponseField name="page_views" type="integer (int64)" required>
          Estimated page views on this device type.
        </ResponseField>

        <ResponseField name="users" type="integer (int64)" required>
          Estimated unique users on this device type.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="domain_breakdown" type="DomainBreakdownEntry[]">
      Users per publisher domain within this expression's audience.

      <Expandable title="DomainBreakdownEntry">
        <ResponseField name="domain" type="string" required>
          Publisher domain name.
        </ResponseField>

        <ResponseField name="page_views" type="integer (int64)" required>
          Estimated page views on this domain.
        </ResponseField>

        <ResponseField name="users" type="integer (int64)" required>
          Estimated unique users on this domain.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="engagement" type="Engagement object">
      How engaged this expression's audience is, beyond its size.

      <Expandable title="Engagement">
        <ResponseField name="engaged_time" type="integer (int64)" required>
          Total engaged time across the audience, in seconds.
        </ResponseField>

        <ResponseField name="engaged_time_per_user" type="number (double)" required>
          Average engaged time per user, in seconds.
        </ResponseField>

        <ResponseField name="video_views" type="integer (int64)" required>
          Total video views across the audience.
        </ResponseField>

        <ResponseField name="views_per_user" type="number (double)" required>
          Average page views per user.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="expression" type="string" required>
      The expression that was evaluated, echoed back so results can be paired with inputs.
    </ResponseField>

    <ResponseField name="time_series_daily" type="TimeSeriesBucket[]">
      Daily time-series: one bucket per calendar day in the window, users and page views for each.

      <Expandable title="TimeSeriesBucket">
        <ResponseField name="bucket" type="string" required>
          The time bucket: an ISO date (e.g. 2026-06-01) for a daily series, an ISO week-of-year number (e.g. 22) for a weekly series.
        </ResponseField>

        <ResponseField name="page_views" type="integer (int64)" required>
          Estimated page views in this bucket.
        </ResponseField>

        <ResponseField name="users" type="integer (int64)" required>
          Estimated unique users in this bucket.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="time_series_weekly" type="TimeSeriesBucket[]">
      Weekly time-series: one bucket per ISO week in the window, users and page views for each.

      <Expandable title="TimeSeriesBucket">
        <ResponseField name="bucket" type="string" required>
          The time bucket: an ISO date (e.g. 2026-06-01) for a daily series, an ISO week-of-year number (e.g. 22) for a weekly series.
        </ResponseField>

        <ResponseField name="page_views" type="integer (int64)" required>
          Estimated page views in this bucket.
        </ResponseField>

        <ResponseField name="users" type="integer (int64)" required>
          Estimated unique users in this bucket.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="total_reach" type="CohortReach object" required>
      Total reach for this expression across the requested workspaces, within the restrict\_to filters.

      <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>
      </Expandable>
    </ResponseField>

    <ResponseField name="workspace_breakdown" type="WorkspaceBreakdownEntry[]">
      Users per requested workspace within this expression's audience.

      <Expandable title="WorkspaceBreakdownEntry">
        <ResponseField name="users" type="integer (int64)" required>
          Estimated unique users in this workspace matching the expression.
        </ResponseField>

        <ResponseField name="workspace_id" type="string (uuid)" required>
          One of the requested workspace IDs.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="unavailable" type="ExpressionUnavailable[]">
  Expressions that were not measured because one or more of their cohorts aren't available in any of the requested workspaces.

  <Expandable title="ExpressionUnavailable">
    <ResponseField name="expression" type="string" required>
      The expression that could not be measured, echoed back so it can be paired with your input.
    </ResponseField>

    <ResponseField name="unavailable_cohorts" type="string[]" required>
      The cohort short ids in this expression that aren't available in any of the requested workspaces. min 1 item.
    </ResponseField>
  </Expandable>
</ResponseField>