> ## Documentation Index > Fetch the complete documentation index at: https://docs.whop.com/llms.txt > Use this file to discover all available pages before exploring further. # Ad Group An Ad Group sits inside an [ad campaign](/api-reference/beta/ad-campaigns/ad-campaign) and controls delivery for [ads](/api-reference/beta/ads/ad). It sets the audience, placements, schedule, budget, and optimization goal for its ads. Use the Ad Groups API to create ad groups in campaigns, list or retrieve targeting and delivery settings, update budgets or targeting, delete groups that should stop running, and pause or resume delivery. It can also search the ad platform's targeting taxonomy for options to target and estimate how many people a draft targeting spec can reach. ## Endpoints | Endpoint | Request | | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | [List Ad Groups](/api-reference/beta/ad-groups/list-ad-groups) | GET `/ad_groups` | | [Create an Ad Group](/api-reference/beta/ad-groups/create-an-ad-group) | POST `/ad_groups` | | [Retrieve an Ad Group](/api-reference/beta/ad-groups/retrieve-an-ad-group) | GET `/ad_groups/{id}` | | [Update an Ad Group](/api-reference/beta/ad-groups/update-an-ad-group) | PATCH `/ad_groups/{id}` | | [Delete an Ad Group](/api-reference/beta/ad-groups/delete-an-ad-group) | DELETE `/ad_groups/{id}` | | [Duplicate an Ad Group](/api-reference/beta/ad-groups/duplicate-an-ad-group) | POST `/ad_groups/{id}/duplicate` | | [Pause an Ad Group](/api-reference/beta/ad-groups/pause-an-ad-group) | POST `/ad_groups/{id}/pause` | | [Unpause an Ad Group](/api-reference/beta/ad-groups/unpause-an-ad-group) | POST `/ad_groups/{id}/unpause` | | [Estimate Ad Group Reach](/api-reference/beta/ad-groups/estimate-ad-group-reach) | POST `/ad_groups/estimate_reach` | | [Search Targeting Options](/api-reference/beta/ad-groups/search-targeting-options) | GET `/ad_groups/targeting_options` | ## Attributes Unique identifier for the ad group, prefixed `adgrp_`. The ad campaign this ad group belongs to. The referenced entity's id. USD value attributed to add-to-cart events. Sums the value sent with each event, normalized to USD; events without a value contribute 0. Whop pixel-attributed add-to-cart events, last-click. Saved audiences this ad group delivers to or excludes. IDs of saved audiences excluded from delivery, prefixed `adaud_`. IDs of saved audiences the ad group delivers to, prefixed `adaud_`. How delivery bids are set in the ad auction. Target-based strategies use `desired_cost_per_result`. Available options: `minimum_cost`, `average_target`, `maximum_target` This ad group's budget, in the ad account's currency. `null` when the budget is set on the campaign instead. Whether `budget_amount` is spent per day (`daily`) or over the ad group's full run (`lifetime`). Available options: `daily`, `lifetime` Clicks divided by impressions, between 0 and 1. The number of clicks. USD value attributed to complete-registration events. Sums the value sent with each event, normalized to USD; events without a value contribute 0. Whop pixel-attributed complete-registration events, last-click. USD value attributed to contact events. Sums the value sent with each event, normalized to USD; events without a value contribute 0. Whop pixel-attributed contact events, last-click. The pixel event optimized for. A standard event, or any custom pixel event name. Where the outcome being optimized for occurs, such as a website visit, social-profile visit, messaging conversation, ad interaction, or lead-form submission. Available options: `website`, `profile`, `instagram_and_facebook`, `instagram_profile`, `messaging`, `on_ad`, `instant_forms`, `instant_forms_and_messenger`, `website_and_instant_forms` Spend divided by attributed add-to-cart events; null when they are not the goal and none are attributed. Spend divided by clicks; 0 when there are no clicks. Spend divided by attributed complete-registration events; null when they are not the goal and none are attributed. Spend divided by attributed contact events; null when contacts are not the goal and none are attributed. Spend divided by attributed leads; null when leads are not a goal and none are attributed. Spend per 1,000 impressions; 0 when there are no impressions. Spend divided by attributed purchases; null when purchases are not a goal and none are attributed. Spend divided by Whop pixel-attributed results; null when nothing Whop-attributable is being optimized for. Spend divided by attributed schedule events; null when schedules are not the goal and none are attributed. Spend divided by attributed submit-application events; null when they are not the goal and none are attributed. Spend divided by unique clicks; null when there are no unique clicks. Spend divided by attributed view-content events; null when they are not the goal and none are attributed. When the ad group was created, as an ISO 8601 timestamp. Whop pixel-attributed custom (merchant-defined) conversion events, last-click, across all custom event names. Whop pixel-attributed custom conversions, keyed by your event name with its last-click count as the value. Empty when no named custom events are attributed. Custom events fired without a name are counted in custom\_conversions but omitted here, so these values sum to at most custom\_conversions. Conversion value attributed to each custom event, keyed by event name like custom\_event\_counts. Sums the value passed to whop.track, normalized to USD; events fired without a value contribute 0. Whether ads in this ad group are delivering right now, and if not, why. When several states apply at once, the highest-precedence one is returned. Available options: `all_ads_rejected`, `rejected`, `draft`, `no_ads`, `campaign_paused`, `paused`, `processing`, `issues`, `scheduled`, `completed`, `ads_off`, `learning_limited`, `learning`, `active` Age, gender, and automatic-audience targeting. Whether automatic audience targeting is on (Advantage+ on Meta). When `true`, the platform can deliver beyond the ages, genders, and detailed targeting you set, treating them as suggestions. Gender targeted. Available options: `all`, `male`, `female` Oldest age targeted. `null` when no maximum is set. Youngest age targeted. `null` when no minimum is set. Cost per result to aim for (`average_target`) or never exceed (`maximum_target`). `null` for `minimum_cost` bidding. Interest, behavior, and demographic targeting, using categories from the ad platform's targeting taxonomy. Entries across interests, behaviors, and demographics are OR'd together (anyone matching any entry is reached), matching Ads Manager's detailed-targeting box. Can't be combined with automatic audience targeting, and unavailable to campaigns with special\_ad\_categories. Behavior categories targeted, such as frequent travelers. The ad platform's ID for the category in its targeting taxonomy. On ad platforms that scope behavior categories, what this one is measured on. Send back the value the targeting\_options endpoint returned alongside the id. Absent on platforms that don't scope them. Available options: `video`, `creator`, `hashtag` Category name, such as `Frequent travelers`. On ad platforms that scope behavior categories, how many days of activity the category covers. Absent on platforms that don't scope them. Demographic categories targeted, such as life events, industries, work employers, job titles, schools, or majors. OR'd with interests and behaviors. The ad platform's ID for the category in its targeting taxonomy. Category name, such as `Recently moved`. Kind of demographic the category belongs to. Available options: `life_events`, `industries`, `income`, `family_statuses`, `work_employers`, `work_positions`, `education_schools`, `education_majors` Interest categories targeted, such as an interest in movies. The ad platform's ID for the category in its targeting taxonomy. Category name, such as `Movies`. Device platforms and operating systems targeted. Operating systems targeted. Empty targets all operating systems. Lowest OS version targeted, such as `18.0`. Absent when any version qualifies. Operating system targeted. Available options: `ios`, `android` Device types targeted. Empty targets all devices. Available options: `mobile`, `desktop` Whether the ad platform automatically mixes and matches this ad group's creatives and copy to find the best-performing combinations. When the ad group stops delivering, as an ISO 8601 timestamp. `null` when it runs until paused. Platform-reported impressions divided by reach. Cap on how often one person sees ads from this ad group. Only available on campaigns with the `awareness` objective; `null` when uncapped. Most times one person can be shown ads from this ad group within the window. Length of the rolling window, in days. The number of impressions. Open issues affecting this ad group and its ads. Empty when there are none. Unique identifier for the issue. A description of what the issue is and how it can be resolved. The ID of the campaign, ad group, or ad the issue is attached to. The type of resource the issue is attached to. Available options: `ad_campaign`, `ad_group`, `ad` Languages targeted, as ISO 639 codes such as `en` or `es`. A region-specific locale with no ISO code appears as its numeric platform locale key. Empty targets all languages. USD value attributed to lead events. Sums the value sent with each event, normalized to USD; events without a value contribute 0. Whop pixel-attributed leads, last-click. Apps the conversation opens in when `conversion_location` is `messaging`. Empty for other conversion locations. Available options: `messenger`, `instagram`, `whatsapp` Minimum the ad group tries to spend each day. `null` when no floor is set. The result the ad group's delivery is optimized to get the most of. Available options: `conversions`, `link_clicks`, `landing_page_views`, `reach`, `impressions`, `engagement`, `conversations`, `video_views`, `two_second_views`, `page_likes`, `social_profile`, `ad_recall_lift`, `event_responses`, `reminders_set`, `lead_generation`, `quality_lead`, `value`, `profile_and_page_engagement` Where ads can appear, per platform. Empty when placements are chosen automatically. Publisher platform where the ad is eligible to appear. Available options: `facebook`, `instagram`, `messenger`, `audience_network`, `threads`, `whatsapp` Positions targeted within the platform, such as `feed` or `story`. Empty targets all of the platform's positions. USD value of pixel-attributed purchases. Whop pixel-attributed purchases, last-click. The number of unique people who saw this. Locations targeted and excluded. Locations excluded from targeting. Country groups can't be excluded. Cities, keyed by the ad platform's location taxonomy. The ad platform's key for the city in its location taxonomy. City name, such as `Austin`. Absent when the platform doesn't return one. Countries, as ISO 3166-1 alpha-2 codes such as `US`. Multi-country groups such as `worldwide` or `europe`. Circular areas, each a coordinate plus a radius. Unit for `radius`. Available options: `mile`, `kilometer` Latitude of the center point. Longitude of the center point. Label for the location, such as a city or address. Absent when the location has no label. Radius around the center point, in `distance_unit`. 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`. ZIP and postal codes. Locations the ad group targets. Cities, keyed by the ad platform's location taxonomy. The ad platform's key for the city in its location taxonomy. City name, such as `Austin`. Absent when the platform doesn't return one. Countries, as ISO 3166-1 alpha-2 codes such as `US`. Multi-country groups such as `worldwide` or `europe`. Circular areas, each a coordinate plus a radius. Unit for `radius`. Available options: `mile`, `kilometer` Latitude of the center point. Longitude of the center point. Label for the location, such as a city or address. Absent when the location has no label. Radius around the center point, in `distance_unit`. 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`. ZIP and postal codes. The Whop pixel conversion event whose attributed count represents results — the optimization goal, or the highest-volume attributed event for campaigns that budget per ad group. Null when the goal isn't a Whop-attributed event. Available options: `purchase`, `lead`, `schedule`, `submit_application`, `contact`, `complete_registration`, `view_content`, `add_to_cart`, `custom`, `messaging_conversation` The merchant-defined event name when result\_event is custom; null for the standard events. The Whop pixel-attributed count behind result\_event. When a campaign's ad groups optimize different goals there is no single result\_event (it is null), and this is instead the sum of each ad group's own attributed results. Null when nothing Whop-attributable is being optimized for. Purchase value divided by spend, both in USD (a currency-neutral ratio); 0 when there is no spend. USD value attributed to schedule events. Sums the value sent with each event, normalized to USD; events without a value contribute 0. Whop pixel-attributed schedule events, last-click. The amount charged, in spend\_currency. The ISO 4217 currency code of all monetary metrics. When the ad group starts delivering, as an ISO 8601 timestamp. `null` when it starts as soon as it's active. Whether the ad group is enabled. `active` and `paused` are set by you; `rejected` means it failed ad review; `duplicating` is a copy still being filled in. Available options: `active`, `paused`, `rejected`, `duplicating` USD value attributed to submit-application events. Sums the value sent with each event, normalized to USD; events without a value contribute 0. Whop pixel-attributed submit-application events, last-click. Display name of the ad group. Unique clicks divided by impressions, between 0 and 1. People who clicked, reported by the Whop pixel, counted once per person. When the ad group was last updated, as an ISO 8601 timestamp. USD value attributed to view-content events. Sums the value sent with each event, normalized to USD; events without a value contribute 0. Whop pixel-attributed view-content events, last-click.
```json AdGroup theme={null} { "id": "adgrp_xxxxxxxxxxx", "ad_campaign": { "id": "adcamp_xxxxxxxxxx" }, "added_to_cart_value": 1050, "added_to_carts": 24, "audiences": { "exclude": [], "include": ["adaud_xxxxxxxxxxx"] }, "bid_type": "minimum_cost", "budget_amount": 100, "budget_type": "daily", "click_through_rate": 0.036, "clicks": 720, "completed_registration_value": 0, "completed_registrations": 16, "contact_value": 0, "contacts": 10, "conversion_event": "purchase", "conversion_location": "website", "cost_per_added_to_cart": 8.33, "cost_per_click": 0.28, "cost_per_completed_registration": 12.5, "cost_per_contact": 20, "cost_per_lead": 13.33, "cost_per_mille": 10, "cost_per_purchase": 25, "cost_per_result": 25, "cost_per_schedule": null, "cost_per_submitted_application": null, "cost_per_unique_click": 0.33, "cost_per_viewed_content": 0.67, "created_at": "2026-06-01T12:00:00Z", "custom_conversions": 5, "custom_event_counts": { "QualifiedCall": 4, "BookedDemo": 1 }, "custom_event_values": { "QualifiedCall": 2000, "BookedDemo": 0 }, "delivery_status": "issues", "demographics": { "automatic": false, "minimum_age": 21, "maximum_age": 45, "gender": "all" }, "desired_cost_per_result": 30, "detailed_targeting": { "interests": [ { "id": "6003139266461", "name": "Movies" } ], "behaviors": [ { "id": "6002714895372", "name": "Frequent travelers", "behavior_type": "video", "period": 15 } ], "demographics": [ { "id": "6015559470583", "name": "Recently moved", "type": "life_events" } ] }, "devices": { "platforms": ["mobile", "desktop"], "operating_systems": [ { "os": "ios", "minimum_version": "18.0" } ] }, "dynamic_creative": false, "ends_at": "2026-07-01T12:00:00Z", "frequency": 1.6, "frequency_cap": null, "impressions": 20000, "issues": [ { "id": "adiss_xxxxxxxxxxx", "message": "The audience is too narrow to deliver. Broaden the targeting to reach more people.", "resource_id": "adgrp_xxxxxxxxxxx", "resource_type": "ad_group" } ], "languages": ["en"], "lead_value": 750, "leads": 15, "message_apps": [], "minimum_daily_spend": 25, "optimization_goal": "conversions", "placements": [ { "platform": "instagram", "positions": ["stream", "story"] } ], "purchase_value": 5200, "purchases": 8, "reach": 12500, "regions": { "include": { "countries": ["US"], "country_groups": [], "regions": ["US-CA"], "cities": [ { "key": "2418779", "name": "Miami" } ], "zips": [], "custom_locations": [ { "latitude": 30.2672, "longitude": -97.7431, "radius": 10, "distance_unit": "mile", "name": "Austin, TX" } ] }, "exclude": { "countries": [], "country_groups": [], "regions": [], "cities": [ { "key": "2421215", "name": "Anchorage" } ], "zips": [], "custom_locations": [ { "latitude": 40.758, "longitude": -73.9855, "radius": 2, "distance_unit": "mile", "name": "Times Square" } ] } }, "result_event": "purchase", "result_event_name": null, "results": 8, "return_on_ad_spend": 26, "schedule_value": 0, "schedules": 0, "spend": 200, "spend_currency": "usd", "starts_at": "2026-06-01T12:00:00Z", "status": "active", "submitted_application_value": 0, "submitted_applications": 0, "title": "US founders", "unique_click_through_rate": 0.03, "unique_clicks": 600, "updated_at": "2026-06-02T12:00:00Z", "viewed_content_value": 0, "viewed_contents": 300 } ```