Meta-Anzeigenbibliothek

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-Referenz. MCP equivalent: Facebook-Anzeigen suchen (and Gewinnerprodukte finden, Kreativ-Inspirationspaket) — see MCP · Werkzeugübersicht.

HOLEN /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=="
}

Der Aufruf der Meta-Anzeigenaufrufe in der App /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.

Eingabewächter (erforderliche Abfrageschlüssel)#

Der Endpunkt gibt seine Haupt-JSON-Daten nur dann zurück, wenn alle folgenden Schlüssel in der Abfragezeichenfolge vorhanden sind (eine leere Zeichenfolge ist zulässig):

Suchbegriff, Stichwort, min, Länder, von, zu, Sortieren, Medienfilter, Seite, max, scrollen, Skalierung, Nischen, seit dem letzten Besuch, zu sehen, Aktivitätsstatus

Falls welche fehlen, handelt es sich bei der Antwort nicht um die übliche Listen-Nutzlast (vermeiden Sie dies in Clients).

Außerdem muss das innere Tor Probe in der Abfrage festlegen oder a angemeldet / API-Schlüssel aufgelöst Sitzung. Mit einem gültigen X-API-Schlüssel, erfüllen Sie die Sitzungsvoraussetzung automatisch. Andernfalls lautet die Antwort:

{"error":"logged_out"}

Alle Abfrageparameter#

Alles, was folgt, wird aus der Abfragezeichenfolge (gleiche Form wie /api/fb-ads (in der App).

isset Gate (muss vorhanden sein; eine leere Zeichenfolge ist zulässig)#

Dieselbe Liste wie Eingangswache oben:
Suchbegriff, Stichwort, min, max, Länder, von, zu, Sortieren, Medienfilter, Seite, scrollen, Skalierung, Nischen, seit dem letzten Besuch, zu sehen, Aktivitätsstatus.

Bei jeder Anfrage wärmstens empfohlen#

Der Handler liest Website, Sprachen, Seitentypfilter, Sortierrichtung, Appsund Themen ohne das durchzumachen isset Liste. Das Dashboard spiegeln und mindestens Website=Alle, Sprachen=Alle, pagetypefilter= (leer = alle Seitentypen), sortdirection=desc, Apps=Alle, Themen=Alle damit das Verhalten der Benutzeroberfläche entspricht und optionale Schlüssel immer definiert sind.

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 Facebook-Anzeigen suchen 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 Stichwort is set and Suchbegriff is empty, searchkeyword=All is applied automatically.

Auth / Sitzung / Test#

Paginierung, Cursor, Dublettenbereinigung#

Stichwortsuche#

Aktive Anzeigen, Skalierung, Medien, Seitentyp, AdScore, Impressionen#

Sortieren#

Ausgaben, Reichweite (mit Fenster), Traffic, Schaltdauer, Preis, Text, Videolänge, aktive Anzeigen auf Seite #

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 erfordert total_active_ads_on_page plus total_active_ads_on_page_growth_{1w,14d,1m,3m} auf 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.

Datumsangaben (Zeichenfolgen, in der Regel J-M-T)#

Datumsbereiche ohne festgelegte Enddaten werden serverseitig normalisiert (z. B. nur von Einstellung → zu kann entsprechend angepasst werden von).

Katalog: Länder, Shops, Nischen, Sprachen, Apps, Themen, Ausschlüsse#

Deep Links, Shuffle, Großbuchstaben#

Validierung / Fehler#

Ungültig min oder max (außerhalb von 0…90000000) kann zu {"error":"value_not_in_range_1"} oder _2oder ein Nicht-JSON falsch Körper in Ausnahmefällen.

Gültige Ergebnisse finden Nischen und Themen (kein API-Schlüssel für diese Routen)#

Integrationen sollten die zulässigen Werte aus dem Discovery-JSON-Datensatz entnehmen und nicht durch Raten ermitteln:

Voreingestellte Nischen-Shortcuts (UI-„Chips“): Die App stellt außerdem benutzerfreundliche Zweibuchstabencodes (z. B. CG, VON, SP) im Nischenfilter. Das sind gültige Segmente in Nischen= genauso, wie der Browser sie sendet.

Pfad / numerische Nischensegmente: Die Werte werden anhand des Nischenkatalogs des Servers aufgelöst (Pfade wie /Bekleidung/... und numerisch IDs (Zuordnung zu kanonischen Namen in der Suche). Ist ein Segment unbekannt, kann es unverändert weitergeleitet werden – bevorzugt /api/niche-counts anstatt sich Strings auszudenken.

Hinweis: /api/niche-counts und /api/themes sind Entdeckung Helfer und verbrauchen die Credits der Meta-Ad-Library-API nicht auf dieselbe Weise /api/adlibrary Das ist richtig. Für Ihre Bereitstellung sind möglicherweise weiterhin eine Anmeldung oder andere Richtlinien vor diesen Routen erforderlich.

Feature-Gates (JSON-Aktualisierung)#

Bei Konten, die nicht über die erforderliche Produktstufe verfügen, liefern bestimmte Filter oder Sortiermodi 200 mit einem kleinen JSON-Body (die Aufforderung zum Upgrade lautet innerhalb des Frequenzbands(nicht immer HTTP 403):

Weitere bemerkenswerte Antworten#

• {"message":"need_account"} — Anonym Probe Anfragen, die über die zulässige Nutzung hinausgehen (Sicherheitsgrenzen für Testversionen).
• Erfolgsdaten: JSON-Objekt mit folgenden Elementen Daten (Anzeigen), optional Nachricht (für Menschen lesbare Filterhinweise), insgesamt + total_relation (computed on every page for API-key / MCP requests; the dashboard UI fetches totals separately via count_only=1), scrollen (deep-pagination cursor), and free-tier credit fields when applicable. insgesamt can still be null for query shapes that post-filter in PHP (e.g. Rangwachstumsfilter). Each ad may include Anzeigenrang (Positionsnummer innerhalb der Marke/Seite) und Rangverlauf (Zeitreihen, die für die Momentum-/Rangwachstumsfilterung im Dashboard verwendet werden). Programmatische und MCP-Nutzdaten enthalten diese Felder, sofern sie in den Suchergebnissen vorhanden sind.