Facebook Ad Library API : le guide développeur pour ads_archive

La Facebook Ad Library API est l'endpoint officiel de la Graph API de Meta, ads_archive, pour rechercher dans l'archive publique d'annonces de façon programmatique. Tu t'authentifies avec un user access token, tu passes le paramètre obligatoire ad_reached_countries, et tu filtres par mots-clés, Page IDs, type d'annonce, dates et plateformes pour recevoir des résultats en JSON. La couverture est limitée : les annonces politiques et de causes sociales dans le monde entier pendant sept ans, plus toutes les annonces diffusées dans l'UE ou au Royaume-Uni pendant un an. Le spend et les impressions reviennent sous forme de fourchettes, ce qui en fait des données de recherche concurrentielle gratuites mais bornées.

Tu as cherché dans l'ad library depuis un navigateur, trouvé ce dont tu avais besoin, et maintenant tu veux les mêmes données en JSON : des extractions programmées, un dashboard de concurrents, un jeu de données de recherche. C'est exactement à ça que sert l'Ad Library API (officiellement la Meta Ad Library API depuis le rebranding), et elle est vraiment gratuite. C'est aussi l'API la plus mal comprise dans l'offre développeur de Meta, parce que la plupart des développeurs arrivent en s'attendant à un accès programmatique à tout ce qu'ils peuvent voir sur le site, et découvrent que l'archive a ses propres règles.

Si tu n'as pas encore travaillé avec l'outil sous-jacent, commence par notre guide complet sur la Meta Ads Library, parce que l'API hérite de chaque propriété de la version web et la restreint ensuite encore davantage. Ce guide couvre la partie qui compte pour les développeurs : ce que l'API renvoie réellement, la configuration de l'accès, l'endpoint ads_archive avec des exemples curl et Python fonctionnels, les limites de taux et les codes d'erreur, et la liste honnête de ce qu'elle ne te donnera jamais, avec ce qu'il faut utiliser à la place.

Ce que couvre réellement la Facebook Ad Library API

Avant d'écrire la moindre ligne de code, assimile la portée, parce qu'elle explique presque toutes les réponses vides que tu obtiendras. L'archive derrière l'API contient exactement deux catégories d'annonces :

Tout le reste n'existe tout simplement pas pour l'API. Une annonce commerciale diffusée uniquement aux États-Unis n'est pas archivée, pas consultable, et pas récupérable. Cette question Stack Overflow de 2019 demandant pourquoi les recherches par mots-clés ne renvoient que des annonces politiques est encore bien classée aujourd'hui parce que la confusion n'a jamais disparu. La recherche par mots-clés sur les annonces commerciales ne fonctionne que là où ces annonces ont été diffusées à des utilisateurs de l'UE ou du Royaume-Uni, puisque ce sont les seules annonces commerciales de l'archive.

Deux changements récents ont encore resserré ça. La couverture du Royaume-Uni s'applique aux annonces diffusées après le 1er juillet 2025, donc l'archive du Royaume-Uni est encore en train de se constituer vers une année glissante complète. Et début octobre 2025, Meta a complètement arrêté d'accepter les annonces politiques, électorales et de causes sociales dans l'UE, en réponse au règlement de l'UE sur la Transparence et le Ciblage de la Publicité Politique. L'archive politique historique de l'UE reste consultable, mais elle est maintenant gelée : les requêtes pour des annonces politiques de l'UE après cette date ne renvoient rien parce qu'aucune n'est en cours.

Pour un développeur, le test pratique est simple. Si ton cas d'usage est la recherche d'annonces politiques n'importe où, ou la recherche de n'importe quelle annonce sur les marchés UE et Royaume-Uni, l'API officielle fonctionne. Si tu as besoin d'annonces commerciales US par mot-clé, elle ne peut pas t'aider, et tu devrais passer directement à la section des alternatives.

Ad Library API contre Marketing API

Les deux sont constamment confondues, et elles ne partagent rien d'autre qu'un nom de domaine. La Marketing API gère la publicité qui t'appartient : elle crée des campagnes, téléverse des creatives, et lit la performance des comptes publicitaires sur lesquels tu as des permissions. L'Ad Library API est un accès en lecture seule à l'archive publique de transparence des annonces de tous les autres.

Les différences traversent chaque couche. La Marketing API nécessite les permissions ads_read ou ads_management et souvent App Review ; l'Ad Library API n'a besoin ni de l'une ni de l'autre. La Marketing API renvoie le spend exact et les résultats exacts de tes annonces ; l'Ad Library API renvoie des fourchettes par bandes pour les annonces politiques et UE/Royaume-Uni des autres. Si tu veux tes propres données de campagne de façon programmatique, tu veux la Marketing API. Ce guide parle de l'autre.

Comment obtenir l'accès à l'Ad Library API

L'accès nécessite trois étapes uniques. Aucune n'est difficile, mais la première implique un délai d'attente, alors commence-la avant d'avoir besoin des données.

Étape 1 : confirme ton identité

Parce que l'archive inclut des données d'annonces politiques, Meta exige que chaque utilisateur de l'API confirme son identité et sa localisation, le même processus que les annonceurs suivent pour diffuser des annonces politiques. Va sur facebook.com/ID en étant connecté, et suis les instructions. Attends-toi à devoir téléverser une pièce d'identité officielle et confirmer ton lieu de résidence. L'approbation prend généralement quelques jours. C'est par compte et à faire une seule fois, mais sauter cette étape est l'échec de configuration le plus courant : ton token sera valide et tes requêtes seront quand même rejetées.

Étape 2 : crée une app sur Meta for Developers

Inscris-toi sur Meta for Developers si ce n'est pas déjà fait, puis crée une nouvelle app depuis My Apps. Le type d'app le plus simple fonctionne ; l'app n'est qu'un conteneur qui te permet de générer des tokens. Tu n'as pas besoin d'y ajouter de produits, et l'Ad Library API ne nécessite pas d'App Review, parce que tu ne fais que lire des données d'archive publiques.

Étape 3 : génère un access token

Ouvre le Graph API Explorer depuis le menu des outils développeur, sélectionne ton app, et génère un user access token. Aucune permission spéciale n'est nécessaire au-delà des valeurs par défaut ; ce qui compte, c'est que l'utilisateur derrière le token ait complété l'étape 1.

Les tokens issus de l'Explorer sont de courte durée, ils expirent en une heure ou deux. Pour tout ce qui dépasse un test rapide, échange-le contre un long-lived token, qui dure environ 60 jours, en utilisant les outils de token du tableau de bord développeur. Les pipelines programmés ont besoin d'une routine de renouvellement, parce que quand le token expire, tes requêtes commencent à échouer avec l'erreur 190 jusqu'à ce que tu en insères un nouveau.

Pour vérifier que tout fonctionne, lance une requête de test dans l'Explorer :

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

Si du JSON revient, tu es dedans.

Interroger l'endpoint ads_archive

Chaque requête est un HTTP GET contre une seule URL :

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

Le segment de version suit les sorties trimestrielles de la Graph API de Meta (v25.0 mi-2026). Deux choses sont obligatoires à chaque appel : ton access_token et ad_reached_countries, un tableau de codes pays ISO (ou ALL) définissant où les annonces que tu veux ont été diffusées. Chaque requête a aussi besoin de search_terms ou de search_page_ids ; omets les deux et l'API rejette l'appel avec une erreur de paramètre au lieu de tout renvoyer. Souviens-toi de la règle de portée : ad_reached_countries=['US'] ne peut faire ressortir que des annonces politiques et de causes sociales, tandis que ['GB'] ou n'importe quel code UE fait aussi ressortir des annonces commerciales.

Les paramètres qui comptent

La liste complète des paramètres se trouve dans la référence ads_archive de Meta, mais voici ceux à partir desquels les requêtes réelles sont construites :

Une poignée d'autres (delivery_by_region, estimated_audience_size_min et max) sont des filtres réservés au politique ; sinon l'API les ignore ou renvoie une erreur.

Choisir tes champs

Par défaut tu obtiens un enregistrement minimal : id, ad_snapshot_url, heures de début et de fin de diffusion, et page_id. Tout le reste doit être demandé explicitement via le paramètre fields. Ceux qu'il vaut la peine de connaître :

• Toutes les annonces : page_name, ad_creative_bodies, ad_creative_link_titles, ad_creative_link_captions, ad_creative_link_descriptions, publisher_platforms, languages, ad_creation_time
• Annonces politiques et de causes sociales uniquement : spend et impressions (fourchettes par bandes, de moins de 100 à plus d'1 M), currency, demographic_distribution, delivery_by_region, estimated_audience_size, bylines
• Annonces diffusées dans l'UE et au Royaume-Uni : eu_total_reach, total_reach_by_location, age_country_gender_reach_breakdown, target_ages, target_gender, target_locations, et beneficiary_payers (UE uniquement)

Les champs qui ne s'appliquent pas à une annonce donnée sont simplement absents de son objet JSON, alors écris ton code de parsing de façon défensive.

Exemple : curl

L'exemple canonique tiré de la propre documentation de Meta, enrichi avec 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"

Exemple : Python avec pagination

Les résultats arrivent par pages, et le vrai travail consiste à les parcourir en boucle. Ce script récupère chaque annonce archivée de la page d'un concurrent telle que diffusée au Royaume-Uni :

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")

Remplace le page ID, le pays et les fields selon ton cas d'usage. Comme code de référence, le propre Ad Library API Script Repository de Meta sur GitHub inclut une interface en ligne de commande simple et des exemples Python, même s'il cible des versions plus anciennes de la Graph API et n'est plus activement mis à jour.

Limites de taux, pagination et erreurs courantes

La pagination est basée sur des curseurs. Chaque réponse contient un tableau data et un objet paging avec des curseurs et une URL next ; tu as atteint la fin quand data revient vide. La taille de page par défaut est de 25 annonces, et le paramètre limit l'augmente. Pousse-la trop haut et tu échanges des problèmes de limite de taux contre des problèmes de timeout sur les requêtes lourdes, c'est pourquoi la plupart des scripts en production se stabilisent autour de quelques centaines d'annonces par page.

Les limites de taux sur ads_archive sont dynamiques et non publiées. Elles s'échelonnent par app et par token, et un usage intensif est throttlé plutôt que mesuré proprement. Trois habitudes te maintiennent sous le plafond : ne demande que les champs dont tu as besoin, contrains les requêtes avec des codes pays et search_page_ids plutôt que des mots-clés larges, et ajoute un backoff exponentiel dès que tu vois l'erreur 613. Pour les jobs récurrents, regrouper jusqu'à 10 page IDs par appel est le gain d'efficacité le moins cher disponible.

Les erreurs que tu rencontreras réellement :

Une bizarrerie structurelle finit par piéger tout le monde : il n'existe pas d'endpoint pour récupérer une seule annonce par son Library ID. Si tu as un ID venant du site, interroge la page de l'annonceur avec search_page_ids et filtre les résultats côté client pour trouver l'id correspondant.

Ce que l'API ne te donnera pas

L'Ad Library API est un outil de transparence, et Meta a délibérément tracé ses limites. Les connaître à l'avance t'évite de concevoir des fonctionnalités que les données ne peuvent pas supporter.

• Aucune métrique de performance. Pas de clics, de CTR, de conversions ou de comptages d'engagement, pour aucune annonce, jamais. Le spend et les impressions n'existent que pour les annonces politiques et UE/Royaume-Uni, et seulement sous forme de fourchettes.
• Aucun fichier creative. Les réponses incluent un ad_snapshot_url qui affiche l'annonce dans un navigateur, mais jamais de fichiers image ou vidéo. Télécharger des médias en masse depuis les pages de snapshot n'est pas pris en charge et entre en conflit avec les conditions d'utilisation de Meta.
• Aucun vrai détail de ciblage. Tu ne peux pas voir les intérêts, les audiences personnalisées, ou les lookalikes. Les annonces UE et Royaume-Uni n'exposent que les sélections larges d'âge, de genre et de localisation.
• Une mémoire commerciale courte. Les annonces non politiques sortent de l'archive un an après leur dernière impression. Les annonces politiques persistent pendant sept ans. Si tu as besoin d'un historique plus long, tu dois collecter en continu et construire ta propre archive.

Rien de tout ça n'est un bug, et aucune requête aussi ingénieuse soit-elle ne les contourne. Quand l'écart compte, tu changes d'outil.

Alternatives quand l'API est trop limitée

Fais correspondre l'outil à l'écart plutôt que de te battre contre l'API officielle.

Tu as besoin d'annonces commerciales en dehors de l'UE et du Royaume-Uni. C'est le gros morceau, et la réponse est de scraper le site Ad Library, qui affiche les annonces commerciales actives dans tous les pays même si l'API ne les sert pas. Des scrapers conçus pour ça et des APIs wrapper (Apify actors à partir d'environ 0,75 $ pour 1 000 annonces, plus des services comme SearchApi et ScrapeCreators qui vendent les mêmes données en JSON propre) gèrent l'automatisation du navigateur pour toi. Les compromis sont réels : tu sors des conditions de l'API officielle, les schémas cassent quand Meta met à jour le site, et prendre cette voie est une décision de risque délibérée qui appartient à l'acheteur, pas quelque chose que nous recommandons.

Tu n'es pas développeur, ou ton équipe ne l'est pas. La plupart des tâches de recherche concurrentielle qui ressemblent à des projets d'API sont en réalité des problèmes d'export : quelqu'un veut les annonces des concurrents ou les données de son propre compte dans un tableur. Les outils d'export en masse sans code couvrent ça sans tokens ni scripts, et notre guide sur l'export des données d'annonces Facebook passe en revue toutes les options de bout en bout.

Tu fais de la recherche formelle. Les universitaires et chercheurs qualifiés peuvent postuler pour la Meta Content Library et son API, la successeure de CrowdTangle, qui couvre les publications publiques et le contenu au-delà des annonces avec une vérification plus stricte et des garanties plus fortes. Pour étudier la portée organique et l'activité coordonnée aux côtés des annonces, c'est l'instrument le plus complet.

Tu n'as besoin que d'une poignée d'annonceurs, occasionnellement. Passe sur l'ingénierie. Le site web plus ses filtres natifs, vérifiés chaque semaine, valent mieux que de maintenir un pipeline de renouvellement de token pour des données que tu pourrais lire en dix minutes.

Foire aux questions

La Facebook Ad Library API est-elle gratuite ? Oui, complètement. Pas de paliers d'utilisation, pas de crédits. Les coûts sont indirects : le temps de vérification d'identité, l'ingénierie des limites de taux, et les restrictions de portée qui peuvent te pousser vers des alternatives payantes.

Puis-je voir toutes les annonces des concurrents dans n'importe quel pays ? Non. Les annonces politiques et de causes sociales dans le monde entier, plus les annonces diffusées dans l'UE ou au Royaume-Uni, constituent toute l'archive. Les annonces commerciales exclusivement US en sont tout simplement absentes.

Puis-je télécharger les images et vidéos des annonces via l'API ? Non. Tu obtiens un ad_snapshot_url pour voir chaque annonce dans un navigateur. Les fichiers médias n'apparaissent jamais dans les réponses, et les récolter en masse depuis les pages de snapshot enfreint les conditions de Meta.

Puis-je rechercher une seule annonce par son Library ID ? Non. Il n'existe pas d'endpoint par ID. Interroge la page de l'annonceur avec search_page_ids et filtre côté client pour l'id que tu veux.

Combien de résultats une requête peut-elle renvoyer ? 25 par page par défaut, augmentable via le paramètre limit, avec une pagination par curseur via paging.next jusqu'à ce que data revienne vide. Quelques centaines par page est le plafond fiable avant que les timeouts ne deviennent fréquents.

Que signifie l'erreur 613 ? Tu as dépassé la limite de taux. Les limites sont dynamiques et non publiées, alors intègre un backoff exponentiel, demande moins de champs, et regroupe les page IDs pour rester sous le seuil.

Ai-je besoin d'App Review pour utiliser l'Ad Library API ? Non. Tu as besoin d'une confirmation d'identité sur facebook.com/ID, d'une app développeur, et d'un user access token. App Review ne s'applique qu'aux données privées d'utilisateurs et aux permissions de compte publicitaire.

Quelle est la limite de taux de l'Ad Library API ? Meta n'en publie pas. Le throttling est dynamique, par app et par token. Traite les erreurs 613 comme le signal, ralentis quand elles apparaissent, et espace les extractions programmées plutôt que de les envoyer en rafale.

Construis en gardant la portée à l'esprit

La Facebook Ad Library API excelle exactement dans ce pour quoi elle a été construite : un accès gratuit, officiel et programmatique à la transparence des annonces politiques dans le monde entier et à toute annonce qui touche des utilisateurs de l'UE et du Royaume-Uni. Dans cette portée, c'est le bon choix à chaque fois, et la configuration (confirmation d'identité, une app développeur, un long-lived token) prend un après-midi plus quelques jours d'attente pour la vérification.

Le mode d'échec consiste à construire contre l'archive que tu as imaginée au lieu de l'archive qui existe réellement. Alors décide à l'avance : la recherche politique ou UE/Royaume-Uni passe par ads_archive ; l'intelligence commerciale tous pays signifie des scrapers ou des APIs de données tierces ; les problèmes en forme de tableur méritent des outils d'export sans code plutôt qu'un projet d'ingénierie. Quel que soit le chemin qui convient, le côté données de la recherche concurrentielle est maintenant la moitié facile. La moitié difficile est ce qu'elle a toujours été : transformer ce que tu apprends des annonces des autres en tes propres tests créatifs, à un volume qui t'apprend réellement quelque chose.