Sign in
Ads

Retrieve an Ad

Retrieves a single ad with stats over the requested window.

get/ads/{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 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.

call_to_action'learn_more' | 'shop_now' | 'sign_up' | 'subscribe' | 'get_started' | 'book_now' | 'apply_now' | 'contact_us' | 'download' | 'order_now' | 'buy_now' | 'get_quote' | 'message_page' | 'whatsapp_message' | 'instagram_message' | 'call_now' | 'get_directions' | 'send_updates' | 'get_offer' | 'watch_more' | 'listen_now' | 'play_game' | 'open_link' | 'no_button' | 'get_offer_view' | 'get_event_tickets' | 'see_menu' | 'request_time' | 'event_rsvp' | 'see_details' | 'view_instagram_profile' | 'null' nullable required

The call-to-action button shown on the ad.

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.

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 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'in_appeal' | 'rejected' | 'in_review' | 'draft' | 'campaign_paused' | 'ad_group_paused' | 'paused' | 'processing' | 'issues' | 'scheduled' | 'learning_limited' | 'learning' | 'active' required

Whether the ad is delivering right now, and if not, why. When several states apply at once, the highest-precedence one is returned.

existing_post_idstring nullable required

The post you pointed this ad at, when it promotes one you already published — a Facebook post, Instagram media, or TikTok video ID. null when the ad uses uploaded creatives.

frequencynumber nullable required

Platform-reported impressions divided by reach.

idstring required

Unique identifier for the ad, prefixed ad_.

impressionsnumber required

The number of impressions.

lead_form_idstring nullable

The ad platform's ID for the instant form the ad uses. Set when the ad references an existing form via lead_form_id, or once a form built from lead_form has been created on the platform.

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.

link_clicksnumber required

Clicks on links in the ad that lead to your destination, as reported by the ad platform. A subset of clicks, which also counts likes, comments, and other interactions with the ad.

multi_advertiser_adsboolean

Whether the ad can appear alongside other advertisers' ads in the same unit. Defaults to true.

platform'meta' | 'tiktok' | 'google' required

The ad platform this ad runs on.

post_idstring nullable required

The post the ad network serves for this ad, as pageID_postID on Meta — the post Meta created for an uploaded creative, or the post being promoted. Use it to open the live post, or to promote the same post from another ad. null until the network has created the post.

post_source'facebook' | 'instagram' | 'null' nullable required

Identifies the network that owns existing_post_id; null when the ad uses uploaded creatives.

post_thumbnail_urlstring nullable required

Preview image of the post named by existing_post_id. null for ads that use uploaded creatives, or until the post's media has been fetched from the network.

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' | 'messaging_conversation' | '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.

status'active' | 'paused' | 'in_review' | 'rejected' required

Whether the ad is enabled. active and paused are set by you; in_review and rejected come from ad review.

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 title of the ad.

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 was last updated, as an ISO 8601 timestamp.

urlstring nullable required

The URL the ad links to, without its query string. Parameters belong in url_parameters; any you send on url are moved there.

url_parametersobject required

Every query parameter appended to the URL, keyed by parameter name — including any you sent on url itself. Whop adds its own click-attribution parameters on top; those are reserved and rejected if you set them. Which keys are reserved depends on the ad's network — Meta: utm_meta_ad_id, utm_meta_adset_id, utm_meta_campaign_id, utm_source, utm_placement, utm_medium, utm_content, utm_adset, utm_whop, wacid, wasid, waid, tw_source, tw_adid; TikTok: waid, wasid, wacid, ad_id, adset_id, campaign_id, utm_source, utm_medium, utm_placement, utm_whop, tw_source, tw_adid.

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

{
  "ad_campaign": {
    "id": "adcamp_xxxxxxxxxxxxxx"
  },
  "ad_group": {
    "id": "adcamp_xxxxxxxxxxxxxx"
  },
  "added_to_cart_value": 1850,
  "added_to_carts": 74,
  "call_to_action": "learn_more",
  "click_through_rate": 0.0261,
  "clicks": 1337,
  "completed_registration_value": 95,
  "completed_registrations": 19,
  "contact_value": 175,
  "contacts": 27,
  "cost_per_added_to_cart": 6.515675675675676,
  "cost_per_click": 0.36,
  "cost_per_completed_registration": 25.37684210526316,
  "cost_per_contact": 17.85777777777778,
  "cost_per_lead": 3.984793388429752,
  "cost_per_mille": 9.42,
  "cost_per_purchase": 12.68842105263158,
  "cost_per_result": 7.653333333333333,
  "cost_per_schedule": 10.48173913043478,
  "cost_per_submitted_application": 40.18,
  "cost_per_unique_click": 0.48,
  "cost_per_viewed_content": 0.2253084112149533,
  "created_at": "2026-01-01T12:00:00.000Z",
  "creatives": [
    {
      "crop": {
        "height": 1000,
        "width": 1000,
        "x": 40
      },
      "format": "vertical",
      "id": "file_xxxxxxxxxxxxxx",
      "media_type": "image",
      "url": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
  ],
  "custom_conversions": 63,
  "custom_event_counts": {
    "booked_detail": 63
  },
  "custom_event_values": {
    "booked_detail": 4820
  },
  "delivery_status": "paused",
  "descriptions": [
    {
      "language": "en",
      "text": "Austin's mobile detailers"
    }
  ],
  "existing_post_id": "xxxxxxxxxxxxxxxx_98765",
  "headlines": [
    {
      "language": "en",
      "text": "Austin's mobile detailers"
    }
  ],
  "id": "ad_xxxxxxxxxxxxxx",
  "impressions": 51204,
  "issues": [
    {
      "id": "adiss_xxxxxxxxxxxxxx",
      "message": "Your ad was rejected for unacceptable business practices. Edit the ad's content and resubmit.",
      "resource_id": "ad_xxxxxxxxxxxxxx",
      "resource_type": "ad"
    }
  ],
  "lead_form": {
    "completion": {
      "button_text": "See our work",
      "button_type": "website",
      "description": "We book coatings two days out, so pick a slot when we ring.",
      "headline": "Thanks — we will call you today",
      "url": "https://shinetime.example/gallery"
    },
    "disclaimer": {
      "body": "Ceramic coating requires the vehicle for two days.",
      "checkboxes": [
        {
          "key": "consent_1",
          "required": true,
          "text": "I agree"
        }
      ],
      "title": "Before you submit"
    },
    "form_type": "higher_intent",
    "intro": {
      "description": "Tell us about your vehicle and we will send a fixed price.",
      "headline": "Get a ceramic coating quote"
    },
    "name": "Ceramic coating quote requests",
    "phone_verification": true,
    "privacy_policy": {
      "link_text": "Shine Time privacy policy",
      "url": "https://shinetime.example/privacy"
    },
    "questions": [
      {
        "format": "multiple_choice",
        "label": "What vehicle are we detailing?",
        "options": [
          {
            "key": "ceramic_coating",
            "logic": {
              "action": "go_to_question",
              "target_question_index": 3
            },
            "value": "Ceramic coating"
          }
        ],
        "type": "custom"
      }
    ]
  },
  "lead_form_id": "1037724182084885",
  "lead_value": 1180,
  "leads": 121,
  "link_clicks": 1071,
  "messaging_config": {
    "keyword": "Book an interior deep clean",
    "message": "Hi! Tell us your vehicle and ZIP and we will send an interior deep clean quote."
  },
  "multi_advertiser_ads": true,
  "platform": "meta",
  "post_id": "xxxxxxxxxxxxxxxx_98765",
  "post_source": "facebook",
  "post_thumbnail_url": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "primary_texts": [
    {
      "language": "en",
      "text": "Austin's mobile detailers"
    }
  ],
  "purchase_value": 9462,
  "purchases": 38,
  "result_event": "custom",
  "result_event_name": "booked_detail",
  "results": 63,
  "return_on_ad_spend": 19.62419113987058,
  "schedule_value": 640,
  "schedules": 46,
  "social_accounts": [
    {
      "id": "adcamp_xxxxxxxxxxxxxx"
    }
  ],
  "spend": 482.16,
  "spend_currency": "usd",
  "status": "paused",
  "submitted_application_value": 300,
  "submitted_applications": 12,
  "title": "Ceramic coating — new ad group",
  "translations": {
    "automatic_languages": [
      "fr"
    ],
    "source_language": "en"
  },
  "unique_clicks": 1012,
  "updated_at": "2026-01-01T12:00:00.000Z",
  "url": "https://shinetime.example/ceramic-coating",
  "url_parameters": {},
  "viewed_contents": 2140
}

Changes

Changed in 12 of the 74 revisions of this API.11429

  • 86b97292852d38See the full diff
    • ▲

      the / response's property type changed from string to object for status

      response-property-type-changed

    • ▲

      the / response's property type changed from string to object for status

      response-property-type-changed

    • ▲

      the / response's property type changed from string to object for status

      response-property-type-changed

    • ○

      added the optional property to the response with the status

      response-optional-property-added

    • ○

      added the required property // to the response with the status

      response-required-property-added

    • ○

      added the required property // to the response with the status

      response-required-property-added

    • ○

      added the required property // to the response with the status

      response-required-property-added

    • ○

      added the required property // to the response with the status

      response-required-property-added

    • ○

      added the required property // to the response with the status

      response-required-property-added

    • ○

      added the required property // to the response with the status

      response-required-property-added

    • ○

      added the required property // to the response with the status

      response-required-property-added

  • 7fcefabddb0a13See the full diff
    • ●

      added the new google enum value to the response property for the response status

      response-property-enum-value-added

    • ○

      added the required property ////////// to the response with the status

      response-required-property-added

    • ○

      added the required property ////////// to the response with the status

      response-required-property-added

    • ○

      added the required property ////////// to the response with the status

      response-required-property-added

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 140d015b99661See the full diff
    • ●

      added the new in_appeal enum value to the response property for the response status

      response-property-enum-value-added

  • ac2b9b1c6a001See the full diff
    • ○

      added the required property to the response with the status

      response-required-property-added

  • 9b2baa68698c1See the full diff
    • ○

      added the optional property to the response with the status

      response-optional-property-added

  • 16c82685be351See the full diff
    • ○

      added the required property to the response with the status

      response-required-property-added

    This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 621705ee8f4a1See the full diff
    • ○

      added the required property to the response with the status

      response-required-property-added

    This revision also has 6 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 4a1a4a5d2c721See the full diff
    • ●

      added the new scheduled enum value to the response property for the response status

      response-property-enum-value-added

  • c301132dbfd71See the full diff
    • ●

      added the new messaging_conversation enum value to the response property for the response status

      response-property-enum-value-added

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • f1020c3ecda41See the full diff
    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    This revision also has 9 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Of the 74 revisions, 1 has no diff computed.