A competitor's Meta ads, as a picture
ads_meta_library is a $0.20 GET request on the Wuthering AI API. See the ads an advertiser, domain or phrase is running on Facebook and Instagram, returned as one full-page image. It answers complete JSON, and a call that fails is not charged.
Endpoint
GET /v1/ads_meta_library
Price per successful call
$0.20
Failed calls
Not charged
curl 'https://wutheringai.com/v1/ads_meta_library?page_id=…&token=YOUR_TOKEN'
What does ads_meta_library return, and when should you call it?
Render Meta's public ad library and return the whole results page as one full-page image, for a named advertiser, a domain, or a phrase.
This is the other half of the ad picture. The Google tools here cover search and YouTube; this covers Facebook, Instagram, Messenger, Threads and the audience network, which is where consumer and much B2B spend actually goes.
Three ways to aim it, and the difference matters: - page_id is one advertiser and nobody else. It is the competitor teardown, and the only aim that cannot drift. - target is a domain, matched against the domain shown on each ad's link card. It catches everyone driving traffic there — the brand, its regional pages, its resellers and affiliates — which is often the more interesting answer. - keyword is a phrase, matched against ad text. It returns the whole field competing on a topic, including companies you had not thought to name.
It answers as a picture because the ads are pictures. The creative, the offer, the headline and the landing-page card are the whole point, and the copy inside a Meta ad is largely pixels. Read the image directly, or pass it to a vision model. Each ad card on it carries a Library ID, the date it started running, and its total active time — an ad running for ninety days has survived the advertiser's own performance review, which makes its message a tested claim rather than a guess.
PAGING: the page shows roughly thirty ads and stops at a 'See more' button nothing can click. Walk backwards through time instead — set started_before to the oldest launch date on the image and call again for the batch before it. wuthering_ads_meta_advertisers reads the same search as dated rows, so it gives you that cutoff exactly rather than by eye.
Rendering takes ten to thirty seconds. Returns: an items array holding one image field, whose value is a URL you can open or pass to a vision model. It is served from this API and is short-lived — read it soon after the call rather than storing it.
Use to see what a competitor or a whole category is actually saying to buyers on Meta. Don't use it for Google or YouTube ads, which are wuthering_ads_advertisers and wuthering_ads_creatives; don't use it to find an advertiser's page_id or to get machine-readable rows, both of which are wuthering_ads_meta_advertisers.
What parameters does ads_meta_library take?
ads_meta_library accepts 13 parameters, none of them required. Array values are comma-separated on the query string.
| Parameter | Type | Required | Description |
|---|---|---|---|
| page_id | string | no | Meta page id of one advertiser — the precise aim, returning that advertiser's ads and nobody else's. Get it from wuthering_ads_meta_advertisers; a page id read off the advertiser's Facebook page instead is a different identifier and returns an empty result rather than an error. An ad-library URL can be pasted whole and the id is taken out of it. |
| target | string | no | Domain to find ads for, for example 'acme.com'. Matched against the domain shown on each ad's link card, so it returns everyone driving traffic there — the brand, its regional pages, its resellers and its affiliates — not only the brand itself. Protocol, path and a leading www are ignored. |
| keyword | string | no | Phrase to match against ad text, for example 'project management'. A category term returns the whole field competing on it. Alongside page_id it narrows to that one advertiser's ads mentioning the phrase, which is how you ask what a competitor says about a specific product. |
| match | string | no | How to match keyword. exact requires the words together, in order, and is the right default for a brand or product name. any matches the words in any order, which widens a category search but drags in unrelated ads. Ignored for target, which is always matched exactly.One of: exact, anyDefaults to exact |
| country | string | no | Two-letter country code for the market whose ads to show, for example 'US' or 'DE', or 'ALL' for every country. Defaults to US, matching the default every other tool here uses. Ad libraries differ sharply by market: the same advertiser runs different offers in each.Defaults to US |
| active_status | string | no | Whether to show ads currently running, ones that have stopped, or both. Defaults to active. Inactive ads are the more interesting half for a teardown — an ad that ran and stopped is a message the advertiser tested and abandoned.One of: active, inactive, allDefaults to active |
| ad_type | string | no | Restrict to one regulated category. Defaults to all. The regulated categories are worth knowing about: Meta is required to publish spend ranges and impression counts for those, so an ad in one carries numbers an ordinary commercial ad does not.One of: all, political_and_issue_ads, housing_ads, employment_ads, financial_products_and_services_adsDefaults to all |
| media_type | string | no | Restrict to one creative format. Defaults to all. none means text-only ads. Narrowing to image makes the captured page far easier to read when a search returns many ads.One of: all, image, video, meme, image_and_meme, noneDefaults to all |
| platforms | array | no | Restrict to particular Meta surfaces. Omit for all of them, which is usually right — an advertiser rarely chooses surfaces deliberately, so filtering mostly just hides ads. Set it when the question is specifically about one placement. |
| languages | array | no | Restrict to ads whose text is in these languages, as ISO codes such as 'en' or 'no'. Omit for all languages. Worth setting for a country where several are common, otherwise the results fill with ads you cannot read. |
| targeted_country | boolean | no | When true, return only ads deliberately TARGETED at the country, rather than every ad merely reachable there. Defaults to false, the broader view. Set it when you need to know a competitor is investing in a market rather than spilling into it.Defaults to false |
| started_after | string | no | Only ads that began running on or after this date, as YYYY-MM-DD. Meta's library starts in 2019. |
| started_before | string | no | Only ads that began running on or before this date, as YYYY-MM-DD. This is how you page: one call reads about thirty ads, newest first, so setting this to the oldest launch date you were given returns the batch before it. Paired with started_after it reads one campaign window. |
Which playbooks call ads_meta_library?
3 of the research playbooks name ads_meta_library in their method. Each is free to read and says where in the sequence the call belongs.
- Is there real demand for this?Test an idea against the cheapest evidence that could kill it — search demand, sustained ad spend, posted salaries, and the words buyers use — and return a verdict with the number that decides it.
- Where is the unoccupied position in this category?Map the category around one domain as an idea maze — the forks it has already run, who took each branch, which walls are still walls and which have moved — then return the one open position with the offer that takes it: buyer, bundle, price metric and message, decided together.
- Who are we really up against?Work April Dunford's positioning sequence from public evidence: the alternatives a prospect would actually use, what only you do, the value that follows, who cares most, and the category that makes all of it obvious.
Reference for ads_meta_library · last updated · published by Wuthering AI