Meta reklam kütüphanesi

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 kılavuzu. MCP equivalent: search_facebook_ads (and find_winning_products, creative_inspiration_pack) — see MCP · araçlar kılavuzu.

AL /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):

arama kelimesi, anahtar kelime, min, ülkeler, ...'den, ...'ye, sıralama, mediafilter, sayfa, max, scroll, ölçeklendirme, nişler, songörüldüğünden beri, görülmüş, 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 ya da a logged-in / API-key–resolved session. With a valid X-API-Anahtarı, 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:
arama kelimesi, anahtar kelime, min, max, ülkeler, ...'den, ...'ye, sıralama, mediafilter, sayfa, scroll, ölçeklendirme, nişler, songörüldüğünden beri, görülmüş, activestatus.

Strongly recommended on every request#

The handler reads web sitesi, diller, pagetypefilter, sıralama yönü, appsve 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 anahtar kelime is set and arama kelimesi 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 gerektirir 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 A-G-Y)#

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

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

Deep links, shuffle, caps#

Validation / errors#

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

Discovering valid nişler ve 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 (örneğin 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 ve /api/themes şunlardır 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 veriler (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.