Meta ad library

GET /api/v1/adlibrary searches Meta (Facebook / Instagram) ads with your API key. /api/adlibrary is a supported alias. Auth and metering match the API reference. MCP equivalent: search_facebook_ads (and find_winning_products, creative_inspiration_pack) — see MCP · tools reference.

GET /api/v1/adlibrary#

curl -sS -G -H "X-API-Key: $WH_API_KEY" "{origin}/api/v1/adlibrary" \
  --data-urlencode "keyword=skincare" \
  --data-urlencode "searchkeyword=adtext" \
  --data-urlencode "countries=US" \
  --data-urlencode "sorting=reach" \
  --data-urlencode "page=0" \
  --data-urlencode "min=" --data-urlencode "max=" \
  --data-urlencode "from=" --data-urlencode "to=" \
  --data-urlencode "mediafilter=" --data-urlencode "scroll=" \
  --data-urlencode "scaling=" --data-urlencode "niches=" \
  --data-urlencode "fromlastseen=" --data-urlencode "tolastseen=" \
  --data-urlencode "activestatus="

{
  "data": [
    {
      "id": "1284756102394857",
      "page_name": "Glow Beauty Co.",
      "ad_creative_body": "This serum changed my skin in 14 days…",
      "ad_snapshot_url": "https://www.facebook.com/ads/library/?id=1284756102394857",
      "media_type": "video",
      "started": "2024-05-12",
      "reach": 184000,
      "ad_rank": 3
    }
  ],
  "total": 240,
  "scroll": "eyJwYWdlIjoxfQ=="
}

The in-app Meta ads views call /api/fb-ads with the same query shape — copy a working request from your browser's network tab and swap the path to /api/v1/adlibrary.

Entry guard (required query keys)#

The endpoint only returns its main JSON payload when all of the following keys are present in the query string (empty string is allowed):

searchkeyword, keyword, min, countries, from, to, sorting, mediafilter, page, max, scroll, scaling, niches, fromlastseen, tolastseen, activestatus

If any are missing, the response is not the usual list payload (avoid this in clients).

Additionally, the inner gate requires trial set in the query or a logged-in / API-key–resolved session. With a valid X-API-Key, you meet the session requirement automatically. Otherwise the response is:

{"error":"logged_out"}

All query parameters#

Everything below is read from the query string (same shape as /api/fb-ads in the app).

isset gate (must be present; empty string is OK)#

Same list as Entry guard above:
searchkeyword, keyword, min, max, countries, from, to, sorting, mediafilter, page, scroll, scaling, niches, fromlastseen, tolastseen, activestatus.

Strongly recommended on every request#

The handler reads website, languages, pagetypefilter, sortdirection, apps, and themes without going through that isset list. Mirror the dashboard and send at least website=All, languages=All, pagetypefilter= (empty = all page types), sortdirection=desc, apps=All, themes=All so behavior matches the UI and optional keys are always defined.

Snake_case aliases (MCP-parity names)#

/api/v1/adlibrary (and the /api/adlibrary alias) also accepts the same snake_case argument names as the MCP search_facebook_ads tool, normalized server-side to the internal keys below (FacebookAdsFilterSpec::publicQueryAliases()). When both names are sent, the internal name wins. Highlights:

On the API route the entry-guard keys are defaulted server-side (Dashboard::fbAdsPublicBaseQuery()), so a request like ?keyword=skincare&last_seen_from=2026-01-01&last_seen_to=2026-02-01 is valid without sending every isset-gate key. When keyword is set and searchkeyword is empty, searchkeyword=All is applied automatically.

Auth / session / trial#

Pagination, cursor, de-duplication#

Keyword search#

Active ads, scaling, media, page type, adscore, impressions#

Sorting#

Spend, reach (with window), traffic, days running, price, copy, video length, active ads on page#

Data dependency — monthly visit growth. mingrowth/maxgrowth range on store_traffic.monthly_visits_growth_{1,3}m on the wlads index. The 1-month field is widely populated; 3-month may return no matches until the indexer backfills that scalar.

Data dependency — wlads % growth filters. minactiveadsgrowth requires total_active_ads_on_page plus total_active_ads_on_page_growth_{1w,14d,1m,3m} on wlads (baselines must be prior counts, not deltas). minreachgrowth uses total_eu_views_growth_pct_{period} when backfilled. Sparse baselines reduce match counts; use broader ranges when testing.

Dates (strings, typically Y-m-d)#

Open-ended date ranges are normalized server-side (e.g. only from set → to may be set to match from).

Catalog: countries, stores, niches, languages, apps, themes, excludes#

Deep links, shuffle, caps#

Validation / errors#

Invalid min or max (outside 0…90000000) can yield {"error":"value_not_in_range_1"} or _2, or a non-JSON false body in edge cases.

Discovering valid niches and themes (no API key on these routes)#

Integrations should learn allowed values from discovery JSON, not from guessing:

Preset niche shortcuts (UI “chips”): The app also exposes human-facing two-letter codes (e.g. CG, BY, SP) in the niche filter. Those are valid segments in niches= the same way the browser sends them.

Path / numeric niche segments: Values are resolved using the server’s niche catalog (paths like /Apparel/... and numeric ids map to canonical names in search). If a segment is unknown, it may be passed through as-is — prefer /api/niche-counts over inventing strings.

Note: /api/niche-counts and /api/themes are discovery helpers and do not consume Meta ad library API credits the same way /api/adlibrary does. Your deployment may still require login or other policy in front of these routes.

Feature gates (upgrade JSON)#

For accounts without the required product tier, certain filters or sort modes return 200 with a small JSON body (upgrade prompt is in-band, not always HTTP 403):

Other notable responses#

• {"message":"need_account"} — Anonymous trial requests beyond allowed usage (trial flow guardrails).
• Success payload: JSON object including data (ads), optional message (human-readable filter hints), total + total_relation (computed on every page for API-key / MCP requests; the dashboard UI fetches totals separately via count_only=1), scroll (deep-pagination cursor), and free-tier credit fields when applicable. total can still be null for query shapes that post-filter in PHP (e.g. rankgrowthfilter). Each ad may include ad_rank (integer position within its brand/page) and rank_history (time series used for momentum / Rank growth filtering in the dashboard). Programmatic and MCP payloads include these fields when present in search results.