Facebook Ad Library API: Der Entwickler-Guide für ads_archive

Die Facebook Ad Library API ist Metas offizieller Graph-API-Endpunkt, ads_archive, um das öffentliche Ad-Archiv programmatisch zu durchsuchen. Du authentifizierst dich mit einem User Access Token, übergibst den erforderlichen ad_reached_countries-Parameter und filterst nach Keywords, Page-IDs, Ad-Typ, Daten und Plattformen, um JSON-Ergebnisse zu erhalten. Die Abdeckung ist begrenzt: politische und gesellschaftspolitische Ads weltweit für sieben Jahre, plus alle Ads, die in der EU oder im UK ausgeliefert wurden, für ein Jahr. Spend und Impressions kommen als Bereiche zurück, was sie zu kostenlosen, aber begrenzten Wettbewerbsrecherche-Daten macht.

Du hast die Ad Library im Browser durchsucht, gefunden, was du brauchtest, und jetzt willst du dieselben Daten in JSON: geplante Abrufe, ein Wettbewerber-Dashboard, einen Forschungsdatensatz. Genau dafür ist die Ad Library API da (offiziell die Meta Ad Library API seit dem Rebrand), und sie ist wirklich kostenlos. Sie ist auch die am meisten missverstandene API in Metas Entwicklerangebot, weil die meisten Entwickler mit der Erwartung ankommen, programmatischen Zugriff auf alles zu bekommen, was sie auf der Website sehen können, und dann feststellen, dass das Archiv seine eigenen Regeln hat.

Wenn du noch nicht mit dem zugrunde liegenden Tool gearbeitet hast, starte mit unserem vollständigen Guide zur Meta Ads Library, denn die API erbt jede Eigenschaft der Web-Version und schränkt sie dann noch weiter ein. Dieser Guide behandelt den Teil, der für Entwickler zählt: was die API tatsächlich zurückgibt, das Zugriffs-Setup, den ads_archive-Endpunkt mit funktionierenden curl- und Python-Beispielen, Rate Limits und Fehlercodes, sowie die ehrliche Liste der Dinge, die sie dir niemals geben wird, zusammen mit dem, was du stattdessen nutzen solltest.

Was die Facebook Ad Library API tatsächlich abdeckt

Bevor du auch nur eine Zeile Code schreibst, verinnerliche den Scope, denn er erklärt fast jede leere Antwort, die du je bekommen wirst. Das Archiv hinter der API enthält genau zwei Kategorien von Ads:

Alles andere existiert für die API schlicht nicht. Eine kommerzielle Ad, die nur in den USA lief, ist nicht archiviert, nicht durchsuchbar und nicht abrufbar. Diese Stack-Overflow-Frage aus 2019, warum Keyword-Suchen nur politische Ads zurückgeben, rankt heute noch, weil die Verwirrung nie verschwunden ist. Keyword-Suche über kommerzielle Ads funktioniert nur dort, wo diese Ads an EU- oder UK-Nutzer ausgeliefert wurden, denn das sind die einzigen kommerziellen Ads im Archiv.

Zwei aktuelle Änderungen haben das weiter verschärft. Die UK-Abdeckung gilt für Ads, die nach dem 1. Juli 2025 liefen, sodass sich das UK-Archiv noch auf ein volles rollierendes Jahr aufbaut. Und Anfang Oktober 2025 hat Meta die Annahme politischer, wahlbezogener und gesellschaftspolitischer Ads in der EU komplett eingestellt, als Reaktion auf die EU-Verordnung zu Transparenz und Targeting politischer Werbung. Das historische EU-Politik-Archiv bleibt abfragbar, ist aber jetzt eingefroren: Abfragen nach EU-Politik-Ads nach diesem Datum liefern nichts, weil keine mehr laufen.

Für einen Entwickler ist der praktische Test einfach. Wenn dein Use Case politische Ad-Recherche irgendwo ist, oder Recherche zu beliebigen Ads in EU- und UK-Märkten, funktioniert die offizielle API. Wenn du US-kommerzielle Ads per Keyword brauchst, kann sie dir nicht helfen, und du solltest direkt zum Abschnitt mit den Alternativen springen.

Ad Library API vs. Marketing API

Die beiden werden ständig verwechselt, und sie teilen sich nichts außer einem Domainnamen. Die Marketing API verwaltet Werbung, die dir gehört: Sie erstellt Kampagnen, lädt Creatives hoch und liest Performance für Werbekonten, auf die du Berechtigungen hast. Die Ad Library API ist ein Read-only-Zugriff auf das öffentliche Transparenzarchiv der Ads von allen anderen.

Die Unterschiede ziehen sich durch jede Ebene. Die Marketing API braucht ads_read- oder ads_management-Berechtigungen und oft App Review; die Ad Library API braucht keins von beidem. Die Marketing API liefert exakten Spend und exakte Ergebnisse für deine Ads; die Ad Library API liefert gebänderte Bereiche für die politischen und EU/UK-Ads anderer Leute. Wenn du deine eigenen Kampagnendaten programmatisch willst, willst du die Marketing API. Dieser Guide handelt von der anderen.

So bekommst du Zugriff auf die Ad Library API

Der Zugriff erfordert drei einmalige Schritte. Keiner davon ist schwer, aber der erste beinhaltet eine Wartezeit, also starte ihn, bevor du die Daten brauchst.

Schritt 1: Bestätige deine Identität

Weil das Archiv politische Ad-Daten enthält, verlangt Meta von jedem API-Nutzer, seine Identität und seinen Standort zu bestätigen, derselbe Prozess, den Werbetreibende durchlaufen, um politische Ads zu schalten. Geh eingeloggt zu facebook.com/ID und folge den Anweisungen. Erwarte, dass du einen amtlichen Ausweis hochladen und deinen Wohnort bestätigen musst. Die Freigabe dauert typischerweise ein paar Tage. Das ist pro Account und einmalig, aber es zu überspringen ist der häufigste Setup-Fehler: Dein Token wird gültig sein, und deine Abfragen werden trotzdem abgelehnt.

Schritt 2: Erstelle eine Meta-for-Developers-App

Melde dich bei Meta for Developers an, falls du das noch nicht getan hast, und erstelle dann über My Apps eine neue App. Der einfachste App-Typ reicht aus; die App ist nur ein Container, mit dem du Tokens generieren kannst. Du musst ihr keine Produkte hinzufügen, und die Ad Library API erfordert kein App Review, weil du nur öffentliche Archivdaten liest.

Schritt 3: Generiere einen Access Token

Öffne den Graph API Explorer aus dem Entwicklertools-Menü, wähle deine App aus und generiere einen User Access Token. Über die Standardwerte hinaus sind keine besonderen Berechtigungen nötig; was zählt, ist, dass der Nutzer hinter dem Token Schritt 1 abgeschlossen hat.

Tokens aus dem Explorer sind kurzlebig und laufen nach ein, zwei Stunden ab. Für alles über einen schnellen Test hinaus tauschst du ihn über die Token-Tools im Entwickler-Dashboard gegen einen Long-Lived Token, der etwa 60 Tage hält. Geplante Pipelines brauchen eine Erneuerungsroutine, denn wenn der Token abläuft, beginnen deine Anfragen mit Fehler 190 zu scheitern, bis du einen frischen einsetzt.

Um zu prüfen, dass alles funktioniert, führe eine Testabfrage im Explorer aus:

ads_archive? ad_reached_countries=['US']&ad_type=POLITICAL_AND_ISSUE_ADS&search_terms='election'

Wenn JSON zurückkommt, bist du drin.

Den ads_archive-Endpunkt abfragen

Jede Anfrage ist ein HTTP-GET gegen eine URL:

https://graph.facebook.com/v25.0/ads_archive

Das Versionssegment folgt Metas vierteljährlichen Graph-API-Releases (v25.0 Stand Mitte 2026). Zwei Dinge sind bei jedem Aufruf verpflichtend: dein access_token und ad_reached_countries, ein Array von ISO-Ländercodes (oder ALL), das definiert, wo die Ads, die du willst, ausgeliefert wurden. Jede Abfrage braucht außerdem entweder search_terms oder search_page_ids; lässt du beide weg, lehnt die API den Aufruf mit einem Parameterfehler ab, statt alles zurückzugeben. Denk an die Scope-Regel: ad_reached_countries=['US'] kann immer nur politische und gesellschaftspolitische Ads zutage fördern, während ['GB'] oder jeder EU-Code auch kommerzielle Ads zutage fördert.

Die Parameter, die zählen

Die vollständige Parameterliste findest du in Metas ads_archive-Referenz, aber das sind die, aus denen echte Abfragen gebaut werden:

Eine Handvoll anderer (delivery_by_region, estimated_audience_size_min und max) sind reine Politik-Filter; ansonsten ignoriert die API sie oder wirft einen Fehler.

Deine Felder auswählen

Standardmäßig bekommst du einen minimalen Datensatz: id, ad_snapshot_url, Start- und Stoppzeiten der Auslieferung und page_id. Alles andere muss explizit über den fields-Parameter angefragt werden. Die, die es zu kennen lohnt:

• Alle Ads: page_name, ad_creative_bodies, ad_creative_link_titles, ad_creative_link_captions, ad_creative_link_descriptions, publisher_platforms, languages, ad_creation_time
• Nur politische und gesellschaftspolitische Ads: spend und impressions (gebänderte Bereiche, von unter 100 bis über 1 Mio.), currency, demographic_distribution, delivery_by_region, estimated_audience_size, bylines
• In der EU und im UK ausgelieferte Ads: eu_total_reach, total_reach_by_location, age_country_gender_reach_breakdown, target_ages, target_gender, target_locations, sowie beneficiary_payers (nur EU)

Felder, die auf eine bestimmte Ad nicht zutreffen, fehlen einfach in ihrem JSON-Objekt, schreib deinen Parsing-Code also defensiv.

Beispiel: curl

Das kanonische Beispiel aus Metas eigenen Docs, erweitert um fields:

curl -G \
 -d "search_terms='california'" \
 -d "ad_type=POLITICAL_AND_ISSUE_ADS" \
 -d "ad_reached_countries=['US']" \
 -d "ad_active_status=ALL" \
 -d "fields=id, page_name, ad_creative_bodies, ad_delivery_start_time, spend, impressions" \
 -d "access_token=<ACCESS_TOKEN>" \
 "https://graph.facebook.com/v25.0/ads_archive"

Beispiel: Python mit Pagination

Ergebnisse kommen seitenweise an, und die eigentliche Arbeit besteht darin, sie zu durchlaufen. Dieses Skript zieht jede archivierte Ad von der Seite eines Wettbewerbers, wie sie im UK ausgeliefert wurde:

import requests

TOKEN = "YOUR_LONG_LIVED_TOKEN"
url = "https://graph.facebook.com/v25.0/ads_archive"
params = {
 "access_token": TOKEN,
 "ad_reached_countries": '["GB"]',
 "search_page_ids": '["123456789"]',
 "ad_active_status": "ALL",
 "fields": "id, page_name, ad_creative_bodies,"
 "ad_delivery_start_time, ad_delivery_stop_time,"
 "publisher_platforms, ad_snapshot_url, eu_total_reach",
 "limit": 250,
}

ads = []
while url:
 resp = requests. get(url, params=params, timeout=60)
 payload = resp. json()
 if "error" in payload:
 raise RuntimeError(payload["error"]["message"])
 ads. extend(payload. get("data", []))
 url = payload. get("paging", {}). get("next")
 params = {} # the next URL already carries every parameter

print(f"Collected {len(ads)} ads")

Tausch Page-ID, Land und fields für deinen Use Case aus. Als Referenzcode enthält Metas eigenes Ad Library API Script Repository auf GitHub ein einfaches Command-Line-Interface und Python-Beispiele, allerdings zielt es auf ältere Graph-API-Versionen ab und wird nicht mehr aktiv gepflegt.

Rate Limits, Pagination und häufige Fehler

Pagination ist Cursor-basiert. Jede Antwort enthält ein data-Array und ein paging-Objekt mit Cursors und einer next-URL; du hast das Ende erreicht, wenn data leer zurückkommt. Die Standard-Seitengröße sind 25 Ads, und der limit-Parameter erhöht sie. Treibst du ihn zu hoch, tauschst du Rate-Limit-Probleme gegen Timeout-Probleme bei schweren Abfragen ein, weshalb sich die meisten Produktionsskripte auf ein paar Hundert Ads pro Seite einpendeln.

Rate Limits auf ads_archive sind dynamisch und nicht veröffentlicht. Sie skalieren pro App und pro Token, und starke Nutzung wird gedrosselt statt sauber gemessen. Drei Gewohnheiten halten dich unter der Grenze: nur die Felder anfragen, die du brauchst, Abfragen mit Ländercodes und search_page_ids statt breiten Keywords einschränken, und exponentielles Backoff einbauen, sobald du Fehler 613 siehst. Für wiederkehrende Jobs ist das Batching von bis zu 10 Page-IDs pro Aufruf der günstigste verfügbare Effizienzgewinn.

Die Fehler, denen du tatsächlich begegnen wirst:

Eine strukturelle Eigenheit erwischt irgendwann jeden: Es gibt keinen Endpunkt, um eine einzelne Ad über ihre Library ID abzurufen. Wenn du eine ID von der Website hast, frag die Seite des Werbetreibenden mit search_page_ids ab und filtere die Ergebnisse clientseitig nach der passenden id.

Was dir die API nicht geben wird

Die Ad Library API ist ein Transparenz-Tool, und Meta hat ihre Grenzen bewusst gezogen. Sie im Voraus zu kennen, erspart dir, Features zu entwerfen, die die Daten nicht hergeben.

• Keine Performance-Kennzahlen. Keine Klicks, CTR, Conversions oder Engagement-Zahlen, für keine Ad, jemals. Spend und Impressions existieren nur für politische und EU/UK-Ads, und nur als Bereiche.
• Keine Creative-Dateien. Antworten enthalten eine ad_snapshot_url, die die Ad im Browser rendert, aber nie Bild- oder Videodateien. Massen-Downloads von Medien über Snapshot-Seiten werden nicht unterstützt und kollidieren mit Metas Nutzungsbedingungen.
• Keine echten Targeting-Details. Du kannst keine Interessen, Custom Audiences oder Lookalikes sehen. EU- und UK-Ads legen nur die groben Auswahlen für Alter, Geschlecht und Standort offen.
• Ein kurzes kommerzielles Gedächtnis. Nicht-politische Ads fallen ein Jahr nach ihrer letzten Impression aus dem Archiv. Politische Ads bleiben sieben Jahre erhalten. Wenn du eine längere Historie brauchst, musst du kontinuierlich sammeln und dein eigenes Archiv aufbauen.

Keins davon sind Bugs, und keine noch so clevere Abfrage kommt daran vorbei. Wenn die Lücke wichtig ist, wechselst du das Werkzeug.

Alternativen, wenn die API zu begrenzt ist

Passe das Tool zur Lücke, statt gegen die offizielle API anzukämpfen.

Du brauchst kommerzielle Ads außerhalb der EU und des UK. Das ist der große Fall, und die Antwort ist, die Ad-Library-Website zu scrapen, die aktive kommerzielle Ads in jedem Land anzeigt, obwohl die API sie nicht ausliefert. Zweckgebaute Scraper und Wrapper-APIs (Apify-Actors ab etwa 0,75 $ pro 1.000 Ads, plus Dienste wie SearchApi und ScrapeCreators, die dieselben Daten als sauberes JSON verkaufen) übernehmen die Browser-Automatisierung für dich. Die Trade-offs sind real: Du bist außerhalb der Bedingungen der offiziellen API, Schemas brechen, wenn Meta die Seite updatet, und diesen Weg zu gehen ist eine bewusste Risikoentscheidung, die der Käufer trägt, nicht etwas, das wir empfehlen.

Du bist kein Entwickler, oder dein Team ist keins. Die meisten Wettbewerbsrecherche-Aufgaben, die wie API-Projekte aussehen, sind eigentlich Export-Probleme: Jemand will Wettbewerber-Ads oder die eigenen Account-Daten in einer Tabelle haben. No-Code-Bulk-Export-Tools decken das ohne Tokens oder Skripte ab, und unser Guide zum Exportieren von Facebook-Ads-Daten geht die Optionen von Anfang bis Ende durch.

Du betreibst formale Forschung. Akademiker und qualifizierte Forscher können sich für die Meta Content Library und ihre API bewerben, die Nachfolgerin von CrowdTangle, die öffentliche Posts und Content über Ads hinaus abdeckt, mit strengerer Prüfung und stärkeren Garantien. Um organische Reichweite und koordinierte Aktivität neben Ads zu untersuchen, ist sie das vollständigere Instrument.

Du brauchst nur gelegentlich eine Handvoll Werbetreibende. Spar dir das Engineering. Die Website plus ihre nativen Filter, wöchentlich geprüft, schlägt es, eine Token-Refresh-Pipeline zu warten, für Daten, die du in zehn Minuten lesen könntest.

Häufig gestellte Fragen

Ist die Facebook Ad Library API kostenlos? Ja, komplett. Keine Nutzungsstufen, keine Credits. Die Kosten sind indirekt: Zeit für die Identitätsverifizierung, Engineering für Rate Limits, und die Scope-Einschränkungen, die dich eventuell zu kostenpflichtigen Alternativen treiben.

Kann ich alle Wettbewerber-Ads in jedem Land sehen? Nein. Politische und gesellschaftspolitische Ads weltweit, plus Ads, die in der EU oder im UK ausgeliefert wurden, sind das gesamte Archiv. Rein US-kommerzielle Ads fehlen schlicht.

Kann ich Ad-Bilder und -Videos über die API herunterladen? Nein. Du bekommst eine ad_snapshot_url, um jede Ad im Browser anzusehen. Mediendateien tauchen niemals in Antworten auf, und sie in großem Stil von Snapshot-Seiten abzugreifen verstößt gegen Metas Bedingungen.

Kann ich eine einzelne Ad über ihre Library ID nachschlagen? Nein. Es gibt keinen By-ID-Endpunkt. Frag die Seite des Werbetreibenden mit search_page_ids ab und filtere clientseitig nach der id, die du willst.

Wie viele Ergebnisse kann eine Abfrage zurückgeben? Standardmäßig 25 pro Seite, erhöhbar über den limit-Parameter, mit Cursor-Pagination über paging.next, bis data leer zurückkommt. Ein paar Hundert pro Seite ist die verlässliche Obergrenze, bevor Timeouts häufig werden.

Was bedeutet Fehler 613? Du hast das Rate Limit überschritten. Limits sind dynamisch und nicht veröffentlicht, bau also exponentielles Backoff ein, frag weniger Felder an und batche Page-IDs, um unter der Schwelle zu bleiben.

Brauche ich App Review, um die Ad Library API zu nutzen? Nein. Du brauchst eine Identitätsbestätigung auf facebook.com/ID, eine Developer-App und einen User Access Token. App Review gilt nur für private Nutzerdaten und Werbekonto-Berechtigungen.

Was ist das Rate Limit der Ad Library API? Meta veröffentlicht keins. Throttling ist dynamisch, pro App und Token. Behandle 613-Fehler als Signal, drossle, wenn sie auftauchen, und staffle geplante Abrufe, statt sie zu bündeln.

Bau mit dem Scope im Hinterkopf

Die Facebook Ad Library API ist exzellent in genau dem, wofür sie gebaut wurde: kostenloser, offizieller, programmatischer Zugriff auf politische Ad-Transparenz weltweit und auf jede Ad, die EU- und UK-Nutzer berührt. Innerhalb dieses Scopes ist sie jedes Mal die richtige Wahl, und das Setup (Identitätsbestätigung, eine Developer-App, ein Long-Lived Token) dauert einen Nachmittag plus ein paar Tage Wartezeit auf die Verifizierung.

Der Fehlermodus ist, gegen das Archiv zu bauen, das du dir vorgestellt hast, statt gegen das, das tatsächlich existiert. Entscheide also im Voraus: Politik- oder EU/UK-Recherche läuft über ads_archive; länderübergreifende kommerzielle Intelligenz bedeutet Scraper oder Dritt-Daten-APIs; Tabellenkalkulations-förmige Probleme verdienen No-Code-Export-Tools statt ein Engineering-Projekt. Welcher Pfad auch passt, die Datenseite der Wettbewerbsrecherche ist jetzt die einfache Hälfte. Die schwere Hälfte ist das, was sie immer war: das, was du aus den Ads anderer Leute lernst, in eigene Creative-Tests zu verwandeln, in einem Volumen, das dich tatsächlich etwas lehrt.