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

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

// Automatically fetches more pages as needed.
for await (const adListResponse of client.ads.list()) {
  console.log(adListResponse.id);
}
{
  "data": [
    {
      "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"
      }
    }
  ],
  "page_info": {
    "end_cursor": "<string>",
    "start_cursor": "<string>",
    "has_next_page": true,
    "has_previous_page": true
  }
}

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 ***************************

Query Parameters

​
after
string | null

Returns the elements in the list that come after the specified cursor.

​
before
string | null

Returns the elements in the list that come before the specified cursor.

​
first
integer | null

Returns the first n elements from the list.

Example:

42

​
last
integer | null

Returns the last n elements from the list.

Example:

42

​
ad_campaign_ids
string[] | null

Only return ads belonging to these ad campaigns (max 100). Can be combined with companyId or used on its own.

Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "VXNlci0xMA==") or integer (such as 4) input value will be accepted as an ID.

​
ad_group_id
string | null

Filter by ad group. Provide exactly one of ad_group_id, ad_campaign_id, or company_id.

​
ad_group_ids
string[] | null

Only return ads belonging to these ad groups (max 100). Can be combined with companyId or used on its own.

Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "VXNlci0xMA==") or integer (such as 4) input value will be accepted as an ID.

​
company_id
string | null

Filter by company. Provide exactly one of ad_group_id, ad_campaign_id, or company_id.

Example:

"biz_xxxxxxxxxxxxxx"

​
created_after
string<date-time> | null

Only return ads created after this timestamp.

Example:

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

​
created_before
string<date-time> | null

Only return ads created before this timestamp.

Example:

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

​
direction
enum<string> | null

The sort direction for results. Defaults to descending.

Available options:
asc,
desc
​
order
enum<string> | null

The field to order results by. Stat columns (spend, impressions, …) sort over the statsFrom/statsTo window and rank across all ads, not just the current page. Defaults to creation date.

Available options:
created_at,
spend,
impressions,
clicks,
reach,
unique_clicks,
results,
click_through_rate,
cost_per_click,
cost_per_mille,
cost_per_result,
frequency,
return_on_ad_spend
​
query
string | null

Case-insensitive substring match against the ad title or ID.

​
stats_from
string<date-time> | null

Inclusive start of the window for each ad's metric fields (spend, impressions, …) and for stats-column sorting. 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 each ad's metric fields and for stats-column sorting. Omit both statsFrom and statsTo for all-time stats.

Example:

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

​
status
enum<string> | null

Filter by status.

Available options:
active,
paused,
inactive,
in_review,
rejected,
flagged
​
campaign_id
string | null

Filter by campaign.

​
order_by
enum<string> | null

Server-side sort column.

Available options:
spend,
return_on_ad_spend,
roas
​
order_direction
enum<string> | null

Sort direction.

Available options:
asc,
desc
​
ad_campaign_id
string | null

Filter by ad campaign. Provide exactly one of ad_group_id, ad_campaign_id, or company_id.

Response

A successful response

The connection type for ExternalAd.

​
data
object[]
required

A list of nodes.

​
page_info
object
required

Information to aid in pagination.