Skip to main content
GET
/
ads
/
{id}
JavaScript
import Whop from '@whop/sdk';

const client = new Whop({
  apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted
});

const ad = await client.ads.retrieve('ad_xxxxxxxxxxxxxxx');

console.log(ad.id);
{
  "id": "ad_xxxxxxxxxxxxxxx",
  "title": "<string>",
  "created_at": "2023-12-01T05:00:00.401Z",
  "updated_at": "2023-12-01T05:00:00.401Z",
  "issues": [
    {
      "subtype": "<string>",
      "resource_type": "<string>",
      "resource_id": "<string>",
      "created_at": "2023-12-01T05:00:00.401Z"
    }
  ],
  "spend": 6.9,
  "impressions": 42,
  "reach": 42,
  "clicks": 42,
  "unique_clicks": 42,
  "frequency": 6.9,
  "click_through_rate": 6.9,
  "unique_click_through_rate": 6.9,
  "return_on_ad_spend": 6.9,
  "purchases": 42,
  "purchase_value": 6.9,
  "leads": 42,
  "cost_per_click": 6.9,
  "cost_per_mille": 6.9,
  "cost_per_result": 6.9,
  "cost_per_purchase": 6.9,
  "cost_per_lead": 6.9,
  "ad_group": {
    "id": "adgrp_xxxxxxxxxxxx"
  },
  "ad_campaign": {
    "id": "adcamp_xxxxxxxxxxx"
  }
}

Authorizations

​
Authorization
string
header
required

A company API key, company scoped JWT, app API key, or user OAuth token. You must prepend your key/token with the word 'Bearer', which will look like Bearer ***************************

Path Parameters

​
id
string
required

The unique identifier of the ad.

Example:

"ad_xxxxxxxxxxxxxxx"

Query Parameters

​
stats_from
string<date-time> | null

Inclusive start of the window for the ad's metric fields (spend, impressions, …). Omit both statsFrom and statsTo for all-time stats.

Example:

"2023-12-01T05:00:00.401Z"

​
stats_to
string<date-time> | null

Inclusive end of the window for the ad's metric fields. Omit both statsFrom and statsTo for all-time stats.

Example:

"2023-12-01T05:00:00.401Z"

Response

A successful response

An ad belonging to an ad group.

​
id
string
required

The unique identifier for this ad.

Example:

"ad_xxxxxxxxxxxxxxx"

​
title
string | null
required

The display title of the ad. Falls back to the creative set caption when unset.

​
status
enum<string>
required

Current delivery status of the ad.

Available options:
active,
paused,
inactive,
in_review,
rejected,
flagged
​
platform
enum<string>
required

The external ad platform this ad is running on (e.g., meta, tiktok).

Available options:
meta,
tiktok
​
created_at
string<date-time>
required

When the ad was created.

Example:

"2023-12-01T05:00:00.401Z"

​
updated_at
string<date-time>
required

When the ad was last updated.

Example:

"2023-12-01T05:00:00.401Z"

​
issues
object[]
required

Open platform issues affecting this ad, deduplicated per object. Empty when there are none.

​
spend
number
required

Amount charged in dollars in the stats window.

Example:

6.9

​
spend_currency
enum<string> | null
required

Currency of spend and the other monetary metric fields.

Available options:
usd,
sgd,
inr,
aud,
brl,
cad,
dkk,
eur,
nok,
gbp,
sek,
chf,
hkd,
huf,
jpy,
mxn,
myr,
pln,
czk,
nzd,
aed,
eth,
ape,
cop,
ron,
thb,
bgn,
idr,
dop,
php,
try,
krw,
twd,
vnd,
pkr,
clp,
uyu,
ars,
zar,
dzd,
tnd,
mad,
kes,
kwd,
jod,
all,
xcd,
amd,
bsd,
bhd,
bob,
bam,
khr,
crc,
xof,
egp,
etb,
gmd,
ghs,
gtq,
gyd,
ils,
jmd,
mop,
mga,
mur,
mdl,
mnt,
nad,
ngn,
mkd,
omr,
pyg,
pen,
qar,
rwf,
sar,
rsd,
lkr,
tzs,
ttd,
uzs,
rub,
btc,
cny,
usdt,
kzt,
awg,
whop_usd,
xau
​
impressions
integer
required

Total impressions (views) on this ad in the stats window.

Example:

42

​
reach
integer
required

Unique users reached in the stats window (deduplicated by the platform).

Example:

42

​
clicks
integer
required

Total clicks on this ad in the stats window.

Example:

42

​
unique_clicks
integer
required

Unique clicks (deduplicated by the platform) in the stats window.

Example:

42

​
frequency
number | null
required

Average number of times each person saw an ad (impressions / reach), as reported by the platform.

Example:

6.9

​
click_through_rate
number
required

Click-through rate as a fraction of impressions (clicks / impressions, 0–1).

Example:

6.9

​
unique_click_through_rate
number | null
required

Unique click-through rate as a fraction of impressions (unique clicks / impressions, 0–1).

Example:

6.9

​
return_on_ad_spend
number
required

Return on ad spend as a ratio (purchaseValue / spend) — 2.5 means $2.50 of attributed purchase value per $1 spent. 0 when there is no spend.

Example:

6.9

​
purchases
integer
required

Number of Whop pixel-attributed purchases (last-click) in the stats window.

Example:

42

​
purchase_value
number
required

Total USD value of Whop pixel-attributed purchases in the stats window.

Example:

6.9

​
leads
integer
required

Number of Whop pixel-attributed leads (last-click) in the stats window.

Example:

42

​
cost_per_click
number
required

Cost per click in dollars (spend / clicks). 0 when there are no clicks.

Example:

6.9

​
cost_per_mille
number
required

Cost per 1,000 impressions in dollars (spend / impressions × 1000). 0 when there are no impressions.

Example:

6.9

​
cost_per_result
number | null
required

Cost in dollars per optimization result (spend / results). 0 when a result is being optimized for but none happened yet; null when nothing is being optimized for.

Example:

6.9

​
cost_per_purchase
number | null
required

Cost in dollars per Whop pixel-attributed purchase (spend / purchases). 0 when purchases are tracked but none happened yet; null when purchases are not a goal and none were attributed.

Example:

6.9

​
cost_per_lead
number | null
required

Cost in dollars per Whop pixel-attributed lead (spend / leads). 0 when leads are tracked but none happened yet; null when leads are not a goal and none were attributed.

Example:

6.9

​
ad_group
object
required

The parent ad group this ad belongs to.

​
ad_campaign
object
required

The ad campaign this ad belongs to.