Sign in

v8

OpenAPI 3.1.02026-08-033623795.0 MB
Ad Groups

Retrieve an Ad Group

Retrieves a single ad group.

get/ad_groups/{id}

Query parameters

stats_fromstring

Start of the stats window.

stats_tostring

End of the stats window.

time_zonestring

IANA timezone the stats window is interpreted in. Defaults to UTC.

attribution_model'last_touch' | 'first_touch'

Attribution model the conversion stats count under (defaults to last_touch). Under both models a journey with any whop ad touch attributes to whop; the model picks which whop touch credits the entity and which non-whop source wins otherwise.

Response

ad group retrieved

added_to_cart_valuenumber required

USD value attributed to add-to-cart events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.

added_to_cartsnumber required

Whop pixel-attributed add-to-cart events, last-click.

bid_type'minimum_cost' | 'average_target' | 'maximum_target' | 'null' nullable required

How delivery bids are set in the ad auction. Target-based strategies use desired_cost_per_result.

budget_amountnumber nullable required

This ad group's budget, in the ad account's currency. null when the budget is set on the campaign instead.

budget_type'daily' | 'lifetime' | 'null' nullable required

Whether budget_amount is spent per day (daily) or over the ad group's full run (lifetime).

click_through_ratenumber required

Clicks divided by impressions, between 0 and 1.

clicksnumber required

The number of clicks.

completed_registration_valuenumber required

USD value attributed to complete-registration events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.

completed_registrationsnumber required

Whop pixel-attributed complete-registration events, last-click.

contact_valuenumber required

USD value attributed to contact events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.

contactsnumber required

Whop pixel-attributed contact events, last-click.

conversion_location'website' | 'profile' | 'instagram_and_facebook' | 'instagram_profile' | 'messaging' | 'on_ad' | 'instant_forms' | 'instant_forms_and_messenger' | 'website_and_instant_forms' | 'null' nullable

Where the outcome being optimized for occurs, such as a website visit, social-profile visit, messaging conversation, ad interaction, or lead-form submission.

cost_per_added_to_cartnumber nullable required

Spend divided by attributed add-to-cart events; null when they are not the goal and none are attributed.

cost_per_clicknumber required

Spend divided by clicks; 0 when there are no clicks.

cost_per_completed_registrationnumber nullable required

Spend divided by attributed complete-registration events; null when they are not the goal and none are attributed.

cost_per_contactnumber nullable required

Spend divided by attributed contact events; null when contacts are not the goal and none are attributed.

cost_per_leadnumber nullable required

Spend divided by attributed leads; null when leads are not a goal and none are attributed.

cost_per_millenumber required

Spend per 1,000 impressions; 0 when there are no impressions.

cost_per_purchasenumber nullable required

Spend divided by attributed purchases; null when purchases are not a goal and none are attributed.

cost_per_resultnumber nullable required

Spend divided by Whop pixel-attributed results; null when nothing Whop-attributable is being optimized for.

cost_per_schedulenumber nullable required

Spend divided by attributed schedule events; null when schedules are not the goal and none are attributed.

cost_per_submitted_applicationnumber nullable required

Spend divided by attributed submit-application events; null when they are not the goal and none are attributed.

cost_per_unique_clicknumber nullable required

Spend divided by unique clicks; null when there are no unique clicks.

cost_per_viewed_contentnumber nullable required

Spend divided by attributed view-content events; null when they are not the goal and none are attributed.

created_atstring required

When the ad group was created, as an ISO 8601 timestamp.

custom_conversionsnumber required

Whop pixel-attributed custom (merchant-defined) conversion events, last-click, across all custom event names.

custom_event_countsobject required

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.

custom_event_valuesobject required

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.

delivery_status'all_ads_rejected' | 'rejected' | 'draft' | 'no_ads' | 'campaign_paused' | 'paused' | 'processing' | 'issues' | 'scheduled' | 'completed' | 'ads_off' | 'learning_limited' | 'learning' | 'active' required

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.

desired_cost_per_resultnumber nullable required

Cost per result to aim for (average_target) or never exceed (maximum_target). null for minimum_cost bidding.

dynamic_creativeboolean

Whether the ad platform automatically mixes and matches this ad group's creatives and copy to find the best-performing combinations.

ends_atstring nullable required

When the ad group stops delivering, as an ISO 8601 timestamp. null when it runs until paused.

frequencynumber nullable required

Platform-reported impressions divided by reach.

idstring required

Unique identifier for the ad group, prefixed adgrp_.

impressionsnumber required

The number of impressions.

languagesstring[]
lead_valuenumber required

USD value attributed to lead events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.

leadsnumber required

Whop pixel-attributed leads, last-click.

message_appsstring[]
minimum_daily_spendnumber nullable

Minimum the ad group tries to spend each day. null when no floor is set.

optimization_goal'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' | 'null' nullable required

The result the ad group's delivery is optimized to get the most of.

purchase_valuenumber required

USD value of pixel-attributed purchases.

purchasesnumber required

Whop pixel-attributed purchases, last-click.

reachnumber required

The number of unique people who saw this.

result_event'purchase' | 'lead' | 'schedule' | 'submit_application' | 'contact' | 'complete_registration' | 'view_content' | 'add_to_cart' | 'custom' | 'null' nullable 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.

result_event_namestring nullable required

The merchant-defined event name when result_event is custom; null for the standard events.

resultsnumber nullable required

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.

return_on_ad_spendnumber required

Purchase value divided by spend, both in USD (a currency-neutral ratio); 0 when there is no spend.

schedule_valuenumber required

USD value attributed to schedule events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.

schedulesnumber required

Whop pixel-attributed schedule events, last-click.

spendnumber required

The amount charged, in spend_currency.

spend_currencystring nullable required

The ISO 4217 currency code of all monetary metrics.

starts_atstring nullable required

When the ad group starts delivering, as an ISO 8601 timestamp. null when it starts as soon as it's active.

status'active' | 'paused' | 'rejected' | 'duplicating' required

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.

submitted_application_valuenumber required

USD value attributed to submit-application events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.

submitted_applicationsnumber required

Whop pixel-attributed submit-application events, last-click.

titlestring nullable required

Display name of the ad group.

unique_click_through_ratenumber nullable required

Unique clicks divided by impressions, between 0 and 1.

unique_clicksnumber required

People who clicked, reported by the Whop pixel, counted once per person.

updated_atstring required

When the ad group was last updated, as an ISO 8601 timestamp.

viewed_content_valuenumber required

USD value attributed to view-content events. Sums the value sent with each event, normalized to USD; events without a value contribute 0.

viewed_contentsnumber required

Whop pixel-attributed view-content events, last-click.

Example response

{
  "bid_type": "minimum_cost",
  "budget_type": "daily",
  "conversion_location": "website",
  "delivery_status": "all_ads_rejected",
  "demographics": {
    "gender": "all"
  },
  "detailed_targeting": {
    "demographics": [
      {
        "type": "life_events"
      }
    ]
  },
  "devices": {
    "operating_systems": [
      {
        "os": "ios"
      }
    ],
    "platforms": [
      "mobile"
    ]
  },
  "issues": [
    {
      "resource_type": "ad_campaign"
    }
  ],
  "message_apps": [
    "messenger"
  ],
  "optimization_goal": "conversions",
  "placements": [
    {
      "platform": "facebook"
    }
  ],
  "regions": {
    "exclude": {
      "custom_locations": [
        {
          "distance_unit": "mile"
        }
      ]
    },
    "include": {
      "custom_locations": [
        {
          "distance_unit": "mile"
        }
      ]
    }
  },
  "result_event": "purchase",
  "status": "active"
}