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

## Endpoints

| Endpoint                                                                | Request                                                                      |
| ----------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| [List Ad Groups](/api-reference/beta/ad-groups/list-ad-groups)          | <Badge color="blue" size="sm" stroke>GET</Badge> `/ad_groups`                |
| [Create Ad Group](/api-reference/beta/ad-groups/create-an-ad-group)     | <Badge color="green" size="sm" stroke>POST</Badge> `/ad_groups`              |
| [Retrieve Ad Group](/api-reference/beta/ad-groups/retrieve-an-ad-group) | <Badge color="blue" size="sm" stroke>GET</Badge> `/ad_groups/{id}`           |
| [Update Ad Group](/api-reference/beta/ad-groups/update-an-ad-group)     | <Badge color="orange" size="sm" stroke>PATCH</Badge> `/ad_groups/{id}`       |
| [Delete Ad Group](/api-reference/beta/ad-groups/delete-an-ad-group)     | <Badge color="red" size="sm" stroke>DELETE</Badge> `/ad_groups/{id}`         |
| [Pause Ad Group](/api-reference/beta/ad-groups/pause-an-ad-group)       | <Badge color="green" size="sm" stroke>POST</Badge> `/ad_groups/{id}/pause`   |
| [Unpause Ad Group](/api-reference/beta/ad-groups/unpause-an-ad-group)   | <Badge color="green" size="sm" stroke>POST</Badge> `/ad_groups/{id}/unpause` |

## Attributes

<Columns cols={2}>
  <Column>
    <ResponseField name="ad_campaign" type="object" required>
      The ad campaign this ad group belongs to, an object with an id.

      <Accordion title="Properties" defaultOpen={true}>
        <ResponseField name="id" type="string" required>
          The referenced entity's id.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="added_to_carts" type="number" required>
      Whop pixel-attributed add-to-cart events, last-click.
    </ResponseField>

    <ResponseField name="audiences" type="object" required>
      Saved-audience targeting: \{ include, exclude } arrays of audience IDs.
    </ResponseField>

    <ResponseField name="bid_type" type="string,null | null" required>
      Bid strategy.

      Available options: `minimum_cost`, `average_target`, `maximum_target`
    </ResponseField>

    <ResponseField name="budget_amount" type="number | null" required>
      Ad-set budget; null when the campaign owns budget (CBO).
    </ResponseField>

    <ResponseField name="budget_type" type="string,null | null" required>
      Whether the budget is daily or lifetime.

      Available options: `daily`, `lifetime`
    </ResponseField>

    <ResponseField name="click_through_rate" type="number" required>
      Clicks divided by impressions, between 0 and 1.
    </ResponseField>

    <ResponseField name="clicks" type="number" required>
      The number of clicks.
    </ResponseField>

    <ResponseField name="completed_registrations" type="number" required>
      Whop pixel-attributed complete-registration events, last-click.
    </ResponseField>

    <ResponseField name="contacts" type="number" required>
      Whop pixel-attributed contact events, last-click.
    </ResponseField>

    <ResponseField name="conversion_event" type="string | null" required>
      The pixel event optimized for. A standard event, or any custom pixel event
      name.
    </ResponseField>

    <ResponseField name="conversion_location" type="string,null | null" required>
      Where results happen: website, profile (IG/FB), messaging (DM), on\_ad (engagement), or the lead destinations (instant\_forms, instant\_forms\_and\_messenger, website\_and\_instant\_forms).

      Available options: `website`, `profile`, `messaging`, `on_ad`, `instant_forms`, `instant_forms_and_messenger`, `website_and_instant_forms`
    </ResponseField>

    <ResponseField name="cost_per_added_to_cart" type="number | null" required>
      Spend divided by attributed add-to-cart events; null when they are not the
      goal and none are attributed.
    </ResponseField>

    <ResponseField name="cost_per_click" type="number" required>
      Spend divided by clicks; 0 when there are no clicks.
    </ResponseField>

    <ResponseField name="cost_per_completed_registration" type="number | null" required>
      Spend divided by attributed complete-registration events; null when they are
      not the goal and none are attributed.
    </ResponseField>

    <ResponseField name="cost_per_contact" type="number | null" required>
      Spend divided by attributed contact events; null when contacts are not the
      goal and none are attributed.
    </ResponseField>

    <ResponseField name="cost_per_lead" type="number | null" required>
      Spend divided by attributed leads; null when leads are not a goal and none are
      attributed.
    </ResponseField>

    <ResponseField name="cost_per_mille" type="number" required>
      Spend per 1,000 impressions; 0 when there are no impressions.
    </ResponseField>

    <ResponseField name="cost_per_purchase" type="number | null" required>
      Spend divided by attributed purchases; null when purchases are not a goal and
      none are attributed.
    </ResponseField>

    <ResponseField name="cost_per_result" type="number | null" required>
      Spend divided by Whop pixel-attributed results; null when nothing
      Whop-attributable is being optimized for.
    </ResponseField>

    <ResponseField name="cost_per_schedule" type="number | null" required>
      Spend divided by attributed schedule events; null when schedules are not the
      goal and none are attributed.
    </ResponseField>

    <ResponseField name="cost_per_submitted_application" type="number | null" required>
      Spend divided by attributed submit-application events; null when they are not
      the goal and none are attributed.
    </ResponseField>

    <ResponseField name="cost_per_viewed_content" type="number | null" required>
      Spend divided by attributed view-content events; null when they are not the
      goal and none are attributed.
    </ResponseField>

    <ResponseField name="created_at" type="string" required>
      When the ad group was created, ISO 8601.
    </ResponseField>

    <ResponseField name="custom_conversions" type="number" required>
      Whop pixel-attributed custom (merchant-defined) conversion events, last-click,
      across all custom event names.
    </ResponseField>

    <ResponseField name="demographics" type="object" required>
      Demographic targeting: automatic (Advantage+), age range, gender.
    </ResponseField>

    <ResponseField name="desired_cost_per_result" type="number | null" required>
      Target/cap cost for average\_target / maximum\_target.
    </ResponseField>

    <ResponseField name="devices" type="object" required>
      Device targeting: platforms and operating systems.
    </ResponseField>

    <ResponseField name="dynamic_creative" type="boolean" required>
      Whether ads within this ad group have their creatives and copy dynamically AB
      tested.
    </ResponseField>

    <ResponseField name="ends_at" type="string | null" required>
      Schedule end, ISO 8601.
    </ResponseField>

    <ResponseField name="frequency" type="number | null" required>
      Platform-reported impressions divided by reach.
    </ResponseField>

    <ResponseField name="frequency_cap" type="object | null" required>
      Impression cap; only valid for reach optimization.
    </ResponseField>

    <ResponseField name="id" type="string" required>
      Unique identifier for the ad group.
    </ResponseField>

    <ResponseField name="impressions" type="number" required>
      The number of impressions.
    </ResponseField>

    <ResponseField name="issues" type="object[]" required>
      Open issues affecting this ad group. Empty when there are none.

      <Accordion title="Properties" defaultOpen={true}>
        <ResponseField name="id" type="string" required>
          Unique identifier for the issue.
        </ResponseField>

        <ResponseField name="message" type="string" required>
          A description of what the issue is and how it can be resolved.
        </ResponseField>

        <ResponseField name="resource_id" type="string | null" required>
          The ID of the campaign, ad group, or ad the issue is attached to.
        </ResponseField>

        <ResponseField name="resource_type" type="string" required>
          The type of resource the issue is attached to.

          Available options: `ad_campaign`, `ad_group`, `ad`
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="languages" type="string[]" required>
      Targeted languages as ISO 639 codes (e.g. en, es). Region-specific Meta
      locales without an ISO mapping appear as their numeric Meta locale key. Empty
      \= all languages.
    </ResponseField>

    <ResponseField name="leads" type="number" required>
      Whop pixel-attributed leads, last-click.
    </ResponseField>

    <ResponseField name="message_apps" type="string[]" required>
      For messaging destinations: the apps to message on (messenger, instagram,
      whatsapp). Empty otherwise.
    </ResponseField>

    <ResponseField name="minimum_daily_spend" type="number | null" required>
      Daily spend floor within the budget.
    </ResponseField>

    <ResponseField name="optimization_goal" type="string | null" required>
      What the ad group optimizes for.
    </ResponseField>

    <ResponseField name="placements" type="object[]" required>
      Targeted placements as \{ platform, positions }. Empty = automatic (Advantage+) placements.
    </ResponseField>

    <ResponseField name="purchase_value" type="number" required>
      USD value of pixel-attributed purchases.
    </ResponseField>

    <ResponseField name="purchases" type="number" required>
      Whop pixel-attributed purchases, last-click.
    </ResponseField>

    <ResponseField name="reach" type="number" required>
      The number of unique people who saw this.
    </ResponseField>

    <ResponseField name="regions" type="object" required>
      Geo targeting: include/exclude countries, regions (ISO 3166-2 states, e.g.
      US-CA), cities, zips.
    </ResponseField>

    <ResponseField name="result_event" type="string,null | null" required>
      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`
    </ResponseField>

    <ResponseField name="result_event_name" type="string | null" required>
      The merchant-defined event name when result\_event is custom; null for the
      standard events.
    </ResponseField>

    <ResponseField name="return_on_ad_spend" type="number" required>
      Purchase value divided by spend; 0 when there is no spend.
    </ResponseField>

    <ResponseField name="schedules" type="number" required>
      Whop pixel-attributed schedule events, last-click.
    </ResponseField>

    <ResponseField name="spend" type="number" required>
      The amount charged, in spend\_currency.
    </ResponseField>

    <ResponseField name="spend_currency" type="string | null" required>
      The ISO 4217 currency code of all monetary metrics.
    </ResponseField>

    <ResponseField name="starts_at" type="string | null" required>
      Schedule start, ISO 8601.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Delivery status of the ad group.

      Available options: `active`, `paused`, `rejected`
    </ResponseField>

    <ResponseField name="submitted_applications" type="number" required>
      Whop pixel-attributed submit-application events, last-click.
    </ResponseField>

    <ResponseField name="title" type="string | null" required>
      The display title of the ad group.
    </ResponseField>

    <ResponseField name="unique_click_through_rate" type="number | null" required>
      Unique clicks divided by impressions, between 0 and 1.
    </ResponseField>

    <ResponseField name="unique_clicks" type="number" required>
      The number of unique clicks.
    </ResponseField>

    <ResponseField name="updated_at" type="string" required>
      When the ad group was last updated, ISO 8601.
    </ResponseField>

    <ResponseField name="viewed_contents" type="number" required>
      Whop pixel-attributed view-content events, last-click.
    </ResponseField>
  </Column>

  <Column>
    <div className="api-resource-sticky-example">
      ```json AdGroup theme={null}
      {
      	"ad_campaign": {
      		"id": "adcamp_xxxxxxxxxx"
      	},
      	"added_to_carts": 24,
      	"audiences": {
      		"exclude": [],
      		"include": ["aud_xxxxxxxxxxx"]
      	},
      	"bid_type": "minimum_cost",
      	"budget_amount": 100,
      	"budget_type": "daily",
      	"click_through_rate": 0.036,
      	"clicks": 720,
      	"completed_registrations": 16,
      	"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_viewed_content": 0.67,
      	"created_at": "2026-06-01T12:00:00Z",
      	"custom_conversions": 5,
      	"demographics": {
      		"age_max": 45,
      		"age_min": 21,
      		"gender": "all"
      	},
      	"desired_cost_per_result": 30,
      	"devices": {
      		"platforms": ["mobile", "desktop"]
      	},
      	"dynamic_creative": false,
      	"ends_at": "2026-07-01T12:00:00Z",
      	"frequency": 1.6,
      	"frequency_cap": null,
      	"id": "adgrp_xxxxxxxxxxx",
      	"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"],
      	"leads": 15,
      	"message_apps": [],
      	"minimum_daily_spend": 25,
      	"optimization_goal": "purchase",
      	"placements": [
      		{
      			"platform": "instagram",
      			"positions": ["feed", "stories"]
      		}
      	],
      	"purchase_value": 5200,
      	"purchases": 8,
      	"reach": 12500,
      	"regions": {
      		"countries": ["US"]
      	},
      	"result_event": "purchase",
      	"result_event_name": null,
      	"return_on_ad_spend": 26,
      	"schedules": 0,
      	"spend": 200,
      	"spend_currency": "usd",
      	"starts_at": "2026-06-01T12:00:00Z",
      	"status": "active",
      	"submitted_applications": 0,
      	"title": "US founders",
      	"unique_click_through_rate": 0.03,
      	"unique_clicks": 600,
      	"updated_at": "2026-06-02T12:00:00Z",
      	"viewed_contents": 300
      }
      ```
    </div>
  </Column>
</Columns>