GET /v1/winners
Search winning ads
Find winning e-commerce ads from the Meta Ad Library (EU/UK delivered ads, confirmed e-commerce shops only). Winner = live 21+ days by default. Each result: the ad's link on the Ad Library, the brand and its shop link, format, days live, versions (Meta's count of ads sharing the creative), active or stopped, EU reach (Meta's total, the only number of people) with the day it was read, the share of Meta's age x gender breakdown in the country / segment you filtered on (a share, never people), and the verbatim hook when its script was cut into sections. A field we don't have is absent, never guessed. No media and no person-name search. Costs 5 credits per search (0 if nothing matches).
Cost: 5 credits per call. A call that returns nothing costs 0.
Parameters
Parameter Type What it does nichestring niche of the keyword search that found the brand (see filters) countrystring 2-letter code: ads with Meta reach in that country, e.g. FR formatstring Meta's display format: VIDEO, IMAGE, DCO, DPA, CAROUSEL… (creative types like UGC are not labelled yet) hook_typestring not measured yet: returns nothing agestring: 13-17, 18-24, 25-34, 35-44, 45-54, 55-64, 65+ genderstring: female, male activeboolean true = still running at our last read, false = stopped min_days_liveinteger default 21 Min 0. max_days_liveinteger Min 0. min_eu_reachinteger Min 0. min_country_sharenumber needs country: the country's minimum share of Meta's breakdown, 0 to 1 Min 0. Max 1. min_segment_sharenumber needs age or gender: the segment's minimum share of Meta's breakdown Min 0. Max 1. min_versionsinteger Min 0. has_scriptboolean true = only ads whose script is cut into sections started_afterstring started_beforestring sortstring: country_share, days_live, eu_reach, newest, segment_share, versions default: eu_reach if a country, age or gender is given, else days_live limitinteger default 20 Min 1. Max 50. offsetinteger Min 0. Max 1000.
Errors 400A parameter is refused (the answer lists the accepted values). Not billed. 401Missing, unknown or revoked API key. 402Not enough credits for this call. Credits never expire; top up with a pack. 429Too many requests for this key. Wait Retry-After seconds. Not billed. 503Server busy or a query took too long. Retry. Not billed.
Request
curl -s "https://api.askposeidon.app/v1/winners?niche=weight%20loss&country=FR&format=VIDEO&has_script=true&limit=2" \
-H "Authorization: Bearer $POSEIDON_API_KEY"Response
{
"data": {
"filters_used": {
"niche": "weight loss",
"format": "VIDEO",
"country": "FR",
"has_script": true,
"min_days_live": 21,
"sort": "eu_reach",
"limit": 2,
"offset": 0
},
"matching_ads": 6,
"matching_ads_with_script": 6,
"results": [
{
"ad_id": "862034243491035",
"library_url": "https://www.facebook.com/ads/library/?id=862034243491035",
"format": "VIDEO",
"active": true,
"status_read_on": "2026-11-12",
"source": "Meta Ad Library (ad fields: dates, status, format, versions, landing link)",
"start_date": "2026-03-08",
"days_live": 249,
"versions": 1,
"landing_url": "https://epycure.com/products/boost-metabolisme",
"brand": {
"page_id": "2218331548432159",
"name": "Epycure",
"shop_domain": "epycure.com",
"shop_url": "https://epycure.com",
"shop_platform": "shopify",
"niche_of_search": "weight loss"
},
"eu_reach": {
"total": 2766753,
"label": "EU reach (Meta's total)",
"read_on": "2026-11-12",
"source": "Meta Ad Library (public ad page, read by Poseidon)",
"country": {
"code": "FR",
"share_of_meta_breakdown": 1.0
}
},
"hook": {
"text": "J'ai perdu 10 kilos en 3 mois, comment t'expliques que ça marche aussi bien ?",
"labelled_by": "AI section labelling (Claude Fable)"
},
"has_script": true
},
{
"ad_id": "2112259736053955",
"library_url": "https://www.facebook.com/ads/library/?id=2112259736053955",
"format": "VIDEO",
"active": true,
"status_read_on": "2026-11-12",
"source": "Meta Ad Library (ad fields: dates, status, format, versions, landing link)",
"start_date": "2026-09-11",
"days_live": 62,
"versions": 2,
"landing_url": "https://emulse.com/pages/5-raisons-listicles-immunite",
"brand": {
"page_id": "110514998585916",
"name": "Emulse",
"shop_domain": "emulse.com",
"shop_url": "https://emulse.com",
"shop_platform": "shopify",
"niche_of_search": "weight loss"
},
"eu_reach": {
"total": 1736020,
"label": "EU reach (Meta's total)",
"read_on": "2026-11-12",
"source": "Meta Ad Library (public ad page, read by Poseidon)",
"country": {
"code": "FR",
"share_of_meta_breakdown": 0.8786
}
},
"hook": {
"text": "Non, mes pâtes n'ont pas bon goût. Si je les lèche, c'est parce que ça brûle.",
"labelled_by": "AI section labelling (Claude Fable)"
},
"has_script": true
}
]
},
"meta": {
"endpoint": "search_winners",
"api_version": "1.1.0",
"credits_charged": 5,
"credits_left": 527,
"answered_at": "2026-11-12T22:11:37+00:00",
"coverage": "Ads delivered in the EU or UK only. The only number of people shown is Meta's EU total reach (eu_reach, \"EU reach (Meta's total)\"), as read on the date shown. Meta publishes no spend or impressions for commercial ads. Countries, ages and genders are shown only as shares of Meta's age x gender breakdown of the same read, never as numbers of people: Meta's breakdown rows do not add up to its EU total (measured 0.93x to 1.10x on 3,820 reads), so a country figure in people would not be a fact.",
"notes": [
"A winner is an ad live for at least 21 days: days between Meta's start date and its stop date, or our last read if it is still active. Override with min_days_live.",
"niche = the niche of the keyword search that found the brand on the Ad Library. It is a fact about our search, not a judgment of the brand: a brand found by 'weight loss' may sell something else."
]
}
}