> ## 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`.
</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="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="expression" type="string" required>
      The expression that was evaluated, echoed back so results can be paired with inputs.
    </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 in the last 30 days.
        </ResponseField>

        <ResponseField name="users" type="integer (int64)" required>
          Estimated unique users in the last 30 days.
        </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>