---
title: "Estimate Ad Group Reach"
method: POST
path: "/ad_groups/estimate_reach"
tags: ["Ad Groups"]
---

# Estimate Ad Group Reach

`POST /ad_groups/estimate_reach`

Estimates how many people a draft targeting spec can reach, before an ad group is created. The body takes the same targeting fields as creating an ad group — `regions`, `demographics`, `detailed_targeting`, `audiences`, `languages`, and `devices` — and nothing is persisted.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `account_id` string — Account to estimate on behalf of. Defaults to the authenticated account.
  - `audiences` AdGroupAudiencesBody — Saved audiences to deliver to or exclude. Can't be combined with demographics.automatic.
    - `exclude` string[] — IDs of saved audiences to exclude from delivery, prefixed `adaud_`.
    - `include` string[] — IDs of saved audiences to deliver to, prefixed `adaud_`.
  - `demographics` AdGroupDemographicsBody — Age, gender, and automatic-audience targeting.
    - `automatic` boolean — Turn on automatic audience targeting (Advantage+ on Meta): the platform can deliver beyond the ages, genders, and detailed targeting you set, treating them as suggestions.
    - `gender` 'all' | 'male' | 'female' — Gender to target.
    - `maximum_age` integer — Oldest age to target.
    - `minimum_age` integer — Youngest age to target.
  - `detailed_targeting` AdGroupDetailedTargetingBody — Interest, behavior, and demographic targeting, using categories from the ad platform's targeting taxonomy. At most 100 entries per section. Can't be combined with demographics.automatic, and unavailable to campaigns with special_ad_categories.
    - `behaviors` object[] — Behavior categories to target, such as frequent travelers.
      - `id` string, required — The ad platform's ID for the category in its targeting taxonomy.
      - `name` string — Category name, such as `Movies`.
    - `demographics` object[] — Demographic categories to target, such as life events or industries.
      - `id` string, required — The ad platform's ID for the category in its targeting taxonomy.
      - `name` string — Category name, such as `Recently moved`.
      - `type` 'life_events' | 'industries' | 'income' | 'family_statuses', required — Kind of demographic the category belongs to.
    - `interests` object[] — Interest categories to target, such as an interest in movies.
      - `id` string, required — The ad platform's ID for the category in its targeting taxonomy.
      - `name` string — Category name, such as `Movies`.
  - `devices` AdGroupDevicesBody — Device platforms and operating systems to target.
    - `operating_systems` object[] — Operating systems to target. Empty targets all operating systems.
      - `minimum_version` string — Lowest OS version to target, such as `18.0`. Omit to target any version.
      - `os` 'ios' | 'android', required — Operating system to target.
    - `platforms` string[] — Device types to target. Empty targets all devices.
  - `languages` string[] — Languages to target, as ISO 639 codes such as `en` or `es`. Empty or omitted targets all languages.
  - `platform` 'meta', required — The ad network the estimate runs on.
  - `regions` AdGroupRegionsBody — Locations to target and exclude.
    - `exclude` AdGroupGeoLocationsBody
      - `cities` object[] — Cities, keyed by the ad platform's location taxonomy.
        - `key` string, required — The ad platform's key for the city in its location taxonomy.
        - `name` string — City name, such as `Austin`.
      - `countries` string[] — Countries, as ISO 3166-1 alpha-2 codes such as `US`.
      - `country_groups` string[] — Multi-country groups such as `worldwide` or `europe`. Include-only — groups can't be excluded.
      - `custom_locations` object[] — Circular areas, each a coordinate plus a radius. At most 200 across include and exclude.
        - `distance_unit` 'mile' | 'kilometer' — Unit for `radius`. Defaults to `mile`.
        - `latitude` number, required — Latitude of the center point.
        - `longitude` number, required — Longitude of the center point.
        - `name` string — Label for the location, such as a city or address.
        - `radius` number, required — Radius around the center point: 1-50 miles or 1-80 kilometers.
      - `regions` string[] — US states and DC, as ISO 3166-2 codes such as `US-CA`. US territories (`PR`, `GU`, `VI`, `AS`, `MP`) and everywhere outside the US are targeted through `countries`.
      - `zips` union[] — ZIP and postal codes, as bare strings or objects with a key.
        - union
          - string
          - object
            - `key` string, required — The ZIP or postal code.
    - `include` AdGroupGeoLocationsBody
      - `cities` object[] — Cities, keyed by the ad platform's location taxonomy.
        - `key` string, required — The ad platform's key for the city in its location taxonomy.
        - `name` string — City name, such as `Austin`.
      - `countries` string[] — Countries, as ISO 3166-1 alpha-2 codes such as `US`.
      - `country_groups` string[] — Multi-country groups such as `worldwide` or `europe`. Include-only — groups can't be excluded.
      - `custom_locations` object[] — Circular areas, each a coordinate plus a radius. At most 200 across include and exclude.
        - `distance_unit` 'mile' | 'kilometer' — Unit for `radius`. Defaults to `mile`.
        - `latitude` number, required — Latitude of the center point.
        - `longitude` number, required — Longitude of the center point.
        - `name` string — Label for the location, such as a city or address.
        - `radius` number, required — Radius around the center point: 1-50 miles or 1-80 kilometers.
      - `regions` string[] — US states and DC, as ISO 3166-2 codes such as `US-CA`. US territories (`PR`, `GU`, `VI`, `AS`, `MP`) and everywhere outside the US are targeted through `countries`.
      - `zips` union[] — ZIP and postal codes, as bare strings or objects with a key.
        - union
          - string
          - object
            - `key` string, required — The ZIP or postal code.

## Response `200`

reach estimated

- ReachEstimate
  - `users_lower_bound` number, nullable, required — Low end of how many people the targeting can reach. Null when the platform couldn't produce an estimate.
  - `users_upper_bound` number, nullable, required — High end of how many people the targeting can reach. Null when the platform couldn't produce an estimate.

## Other responses

- `400` — Invalid Parameters
- `401` — Unauthorized
- `403` — Forbidden

---

[API](https://skmtc.net/whop/apis/whop-api.md) · [All operations](https://skmtc.net/whop/apis/whop-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/whop/whop-api/versions/db0883548bc5/schema)