> This page is for For Developers. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://whop.ferndocs.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://whop.ferndocs.com/_mcp/server. # List ads GET https://api.whop.com/api/v1/ads List ads scoped by ad group, campaign, or company. Required permissions: - `ad_campaign:basic:read` Reference: https://whop.ferndocs.com/for-developers/api-reference/api-reference/ads/list-ad ## Authentication - `Authorization` header (bearer token, 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 ***************************` ## Servers - `https://api.whop.com/api/v1` (Production Whop API, default) - `http://localhost:3000/api/v1` (Development Whop API) ## Request ### Query parameters - `after` (string, optional, nullable) - `before` (string, optional, nullable) - `first` (integer, optional, nullable) - `last` (integer, optional, nullable) - `ad_campaign_ids` (list of string, optional, nullable) - `ad_group_id` (string, optional, nullable) - `ad_group_ids` (list of string, optional, nullable) - `company_id` (string, optional, nullable) - `created_after` (datetime, optional, nullable) - `created_before` (datetime, optional, nullable) - `direction` (enum, optional, nullable) — The direction of the sort. - Allowed values: `asc`, `desc` - `order` (enum, optional, nullable) — The fields ad resources can be ordered by. - Allowed values: `created_at`, `spend`, `return_on_ad_spend` - `query` (string, optional, nullable) - `stats_from` (datetime, optional, nullable) - `stats_to` (datetime, optional, nullable) - `status` (enum, optional, nullable) — The status of an external ad. - Allowed values: `active`, `paused`, `inactive`, `in_review`, `rejected`, `flagged` - `campaign_id` (string, optional, nullable) - `order_by` (enum, optional, nullable) — Columns that the listAds query can sort by. Deprecated — use AdOrder. - Allowed values: `spend`, `return_on_ad_spend`, `roas` - `order_direction` (enum, optional, nullable) — The direction of the sort. - Allowed values: `asc`, `desc` - `ad_campaign_id` (string, optional, nullable) ## Response ### 200 A successful response - `data` (list of AdListItem, required) — A list of nodes. - `page_info` (PageInfo, required) — Information to aid in pagination. ## Errors ### 400 Bad Request Error Bad request - `error` (AdsGetResponsesContentApplicationJsonSchemaError, required) ### 401 Unauthorized Error Unauthorized - `error` (AdsGetResponsesContentApplicationJsonSchemaError, required) ### 403 Forbidden Error Forbidden - `error` (AdsGetResponsesContentApplicationJsonSchemaError, required) ### 404 Not Found Error Not found - `error` (AdsGetResponsesContentApplicationJsonSchemaError, required) ### 422 Unprocessable Entity Error Verification required - `error` (AdsGetResponsesContentApplicationJsonSchemaError, required) ### 500 Internal Server Error Internal server error - `error` (AdsGetResponsesContentApplicationJsonSchemaError, required) ## Types ### AdListItem An ad belonging to an ad group. - `ad_campaign` (AdListItemAdCampaign, required) — The ad campaign this ad belongs to. - `ad_group` (AdListItemAdGroup, required) — The parent ad group this ad belongs to. - `click_through_rate` (double, required) — Click-through rate as a fraction of impressions (clicks / impressions, 0–1). - `clicks` (integer, required) — Total clicks on this ad in the stats window. - `cost_per_click` (double, required) — Cost per click in dollars (spend / clicks). 0 when there are no clicks. - `cost_per_lead` (double, required, nullable) — 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. - `cost_per_mille` (double, required) — Cost per 1,000 impressions in dollars (spend / impressions × 1000). 0 when there are no impressions. - `cost_per_purchase` (double, required, nullable) — 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. - `cost_per_result` (double, required, nullable) — 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. - `created_at` (datetime, required) — When the ad was created. - `frequency` (double, required, nullable) — Average number of times each person saw an ad (impressions / reach), as reported by the platform. - `id` (string, required) — The unique identifier for this ad. - `impressions` (integer, required) — Total impressions (views) on this ad in the stats window. - `issues` (list of AdListItemIssuesItems, required) — Open platform issues affecting this ad, deduplicated per object. Empty when there are none. - `leads` (integer, required) — Number of Whop pixel-attributed leads (last-click) in the stats window. - `platform` (enum, required) — The external ad platform this ad is running on (e.g., meta, tiktok). - Allowed values: `meta`, `tiktok` - `purchase_value` (double, required) — Total USD value of Whop pixel-attributed purchases in the stats window. - `purchases` (integer, required) — Number of Whop pixel-attributed purchases (last-click) in the stats window. - `reach` (integer, required) — Unique users reached in the stats window (deduplicated by the platform). - `return_on_ad_spend` (double, 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. - `spend` (double, required) — Amount charged in dollars in the stats window. - `spend_currency` (enum, required, nullable) — Currency of `spend` and the other monetary metric fields. - Allowed values: `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` - `status` (enum, required) — Current delivery status of the ad. - Allowed values: `active`, `paused`, `inactive`, `in_review`, `rejected`, `flagged` - `title` (string, required, nullable) — The display title of the ad. Falls back to the creative set caption when unset. - `unique_click_through_rate` (double, required, nullable) — Unique click-through rate as a fraction of impressions (unique clicks / impressions, 0–1). - `unique_clicks` (integer, required) — Unique clicks (deduplicated by the platform) in the stats window. - `updated_at` (datetime, required) — When the ad was last updated. ### PageInfo Information about pagination in a connection. - `end_cursor` (string, required, nullable) — When paginating forwards, the cursor to continue. - `has_next_page` (boolean, required) — When paginating forwards, are there more items? - `has_previous_page` (boolean, required) — When paginating backwards, are there more items? - `start_cursor` (string, required, nullable) — When paginating backwards, the cursor to continue. ### AdsGetResponsesContentApplicationJsonSchemaError - `message` (string, required) - `type` (string, required) - `code` (string, optional, nullable) — A short string indicating the specific error code, e.g. 'parameter_missing', 'parameter_invalid', 'invalid_json' - `param` (string, optional, nullable) — The parameter that caused the error, if applicable ### AdListItemAdCampaign The ad campaign this ad belongs to. - `id` (string, required) — The unique identifier for this ad campaign. ### AdListItemAdGroup The parent ad group this ad belongs to. - `id` (string, required) — The unique identifier for this ad group. ### AdListItemIssuesItems A platform-reported issue on an ad object (rejection, policy flag, etc.). - `created_at` (datetime, required) — When the issue was first reported. - `error_code` (string, required, nullable) — Platform-specific error code. - `error_message` (string, required, nullable) — Full error detail from the platform. - `error_summary` (string, required) — Short description of the issue. - `resolution_status` (enum, required) — Current resolution status. - Allowed values: `open`, `resolved`, `acknowledged` - `resource_id` (string, required, nullable) — The Whop ID of the ad object this issue is on (the ad, ad group, or campaign). Null when the issue isn't tied to a local object. - `resource_type` (string, required) — The kind of ad object this issue is on: `ad`, `ad_group`, or `ad_campaign`. Pairs with `resourceId`. ## Examples **Response** ```json { "data": [ { "ad_campaign": { "id": "adcamp_xxxxxxxxxxx" }, "ad_group": { "id": "adgrp_xxxxxxxxxxxx" }, "click_through_rate": 6.9, "clicks": 42, "cost_per_click": 6.9, "cost_per_lead": 6.9, "cost_per_mille": 6.9, "cost_per_purchase": 6.9, "cost_per_result": 6.9, "created_at": "2023-12-01T05:00:00.401Z", "frequency": 6.9, "id": "ad_xxxxxxxxxxxxxxx", "impressions": 42, "issues": [ { "created_at": "2023-12-01T05:00:00.401Z", "error_code": "string", "error_message": "string", "error_summary": "string", "resolution_status": "open", "resource_id": "string", "resource_type": "string" } ], "leads": 42, "platform": "meta", "purchase_value": 6.9, "purchases": 42, "reach": 42, "return_on_ad_spend": 6.9, "spend": 6.9, "spend_currency": "usd", "status": "active", "title": "string", "unique_click_through_rate": 6.9, "unique_clicks": 42, "updated_at": "2023-12-01T05:00:00.401Z" } ], "page_info": { "end_cursor": "string", "has_next_page": true, "has_previous_page": true, "start_cursor": "string" } } ``` **SDK Code** ```python import requests url = "https://api.whop.com/api/v1/ads" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.whop.com/api/v1/ads'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.whop.com/api/v1/ads" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.whop.com/api/v1/ads") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.whop.com/api/v1/ads") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.whop.com/api/v1/ads', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.whop.com/api/v1/ads"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.whop.com/api/v1/ads")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```