Bibliothèque publicitaire Meta

GET /api/v1/adlibrary searches Meta (Facebook / Instagram) ads with your API key. Alias: /api/adlibrary. Same auth and metering as the rest of /api/v1. MCP: search_facebook_ads.

curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/adlibrary?keyword=skincare&searchkeyword=string&countries=US&store_based_in=MX&sorting=relevance&sortdirection=desc&page=0&scroll=string&limit=20&mediafilter=string&activestatus=string&from=string&to=string&fromlastseen=string&tolastseen=string&niches=string&min=string&max=string"

const res = await fetch(`${ORIGIN}/api/v1/adlibrary?keyword=skincare&searchkeyword=string&countries=US&store_based_in=MX&sorting=relevance&sortdirection=desc&page=0&scroll=string&limit=20&mediafilter=string&activestatus=string&from=string&to=string&fromlastseen=string&tolastseen=string&niches=string&min=string&max=string`, {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.WH_API_KEY,
  },
});
const data = await res.json();

import os, requests

res = requests.get(
    f"{ORIGIN}/api/v1/adlibrary?keyword=skincare&searchkeyword=string&countries=US&store_based_in=MX&sorting=relevance&sortdirection=desc&page=0&scroll=string&limit=20&mediafilter=string&activestatus=string&from=string&to=string&fromlastseen=string&tolastseen=string&niches=string&min=string&max=string",
    headers={"X-API-Key": os.environ["WH_API_KEY"]},
)
data = res.json()

{
    "data": [
        {
            "productid": "1284756102394857",
            "page_id": "108897621643793",
            "pageName": "Glow Beauty Co.",
            "countries": [
                "US",
                "CA"
            ],
            "started": "2024-05-12",
            "lastSeen": "2026-03-14",
            "caption": "This serum changed my skin in 14 days…",
            "copy": "This serum changed my skin in 14 days…",
            "urlStore": "https://glowbeautyco.com/products/vitamin-c-serum",
            "daysrunning": 128,
            "countActive": 12,
            "total_active_ads_on_page": 47,
            "ad_rank": 3,
            "adscore": "Winning",
            "total_adspend": 8420,
            "saved": false,
            "hidden": false
        }
    ],
    "total": 240,
    "total_relation": "eq",
    "scroll": "sa:opaque-cursor-token",
    "limit": 20,
    "adspend_cpm": 11,
    "nextscrapetime": 1781686740,
    "message": null
}

{
    "success": false,
    "error": "Invalid or expired scroll token"
}

{
    "success": false,
    "error": "Unauthorized"
}

{
    "success": false,
    "error": "WinningHunter Basic plan or higher required"
}

{
    "success": false,
    "error": "Rate limit exceeded. Max 60 requests per minute."
}

curl -sS -G -H "X-API-Key: $WH_API_KEY" "{origin}/api/v1/adlibrary" \
  --data-urlencode "keyword=skincare" \
  --data-urlencode "countries=US" \
  --data-urlencode "sorting=reach" \
  --data-urlencode "page=0"

On /api/v1/adlibrary, missing entry-guard keys are filled from Dashboard::fbAdsPublicBaseQuery() — you do not need to send every dashboard gate key. When mot-clé is set and searchkeyword is empty, searchkeyword=All is applied.

Niche code discovery (no API-key metering on this path): GET /api/niche-counts → { "niches":[{ "code":"CG","count":… }, …], "total_with_niche":… }. Optional ?refresh=1.

Pagination: page=0, empty scroll first; pass returned scroll with the same filters. Stop when scroll is null. Prefer stable sorts for deep paging.

Snake_case aliases#

Public aliases normalize to internal keys (internal name wins if both are sent):

More filters match the in-app Meta ads dashboard (/api/fb-ads query shape). Copy a working Network tab request and swap the path to /api/v1/adlibrary when unsure.

Response notes:

• 200 bodies are pas wrapped in { "success": true }.
• Each data[] item is a full dashboard card from Utils::process_ads (same shape as Magic AI / brand ads). Key fields include productid, pageName (not page_name), daysrunning (not days_running), urlStore, adscore, saved, hidden. There is no top-level id / ad_url / platform / headline on these cards — use productid et urlStore. Many more enrichment fields may appear (total_adspend, reach histories, Shopify fields, …).
• Active-ads timeline (high signal): total_active_ads_on_page is the current count. Sibling fields total_active_ads_on_page_growth_1w, _14d, _1m, _3m sont absolute historical counts (how many active ads the page had at those lookbacks), not percentages — use them as a 5-point scaling curve.
• Traffic history: when store enrichment is present, store_traffic.monthly_visits_historical (or top-level monthly_visits_historical on some store rows) is ~6 months of monthly visits — prefer it over a single monthly_visits snapshot.
• Top-level may also include nextscrapetime et message (often null).
• Scroll errors: "Invalid or expired scroll token" ou "Scroll token does not match current query filters".
• Credit exhaustion also returns 429 with the credits + purchase envelope (same as other v1 routes).
• Plan gates may return HTTP 200 avec { "upgrade": "standard_reach", "message": "…" } instead of ads.
• Unsupported Meta ad-targeting countries (e.g. MX, CO, CL) return HTTP 400 { "success": false, "error": "invalid_argument", "allowed_values": [...], "hint": "…" } — not an empty 200. For stores based in those markets, pass store_based_in / storebasedin (filters shop_origin_country). Spain (ES) and Brazil (BR) remain valid targeting markets.
• Detected tech stack on cards: technologies (codes such as SH, KV, TA) when enrichment is present.