> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API de la Bibliothèque publicitaire de Meta

> Recherchez dans la Bibliothèque publicitaire de Meta par mot-clé ou par annonceur et recevez en JSON les publicités diffusées sur Facebook, Instagram, Messenger, WhatsApp et Threads, avec leur texte, leurs médias, leur page de destination et leurs plateformes.

Recherchez dans la Bibliothèque publicitaire de Meta en JSON via l’API de tâches asynchrones. Envoyez `taskType` `ADS` avec `platform` `meta_ad_library`, et un mot-clé dans `query` ou l’ID de la page Facebook d’un annonceur dans `pageId`. Une recherche coûte **0.5 crédit par tranche de 30 publicités** renvoyées. Pour trouver l’ID de page d’un annonceur à partir de son nom, envoyez `action` `advertisers`.

## Requête

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "ADS", "payload": { "platform": "meta_ad_library", "pageId": "266556540473351", "country": "US" } }'
```

Soumettez la tâche, puis interrogez `GET /v1/async/task/{id}` ou recevez son webhook. Voir [Tâches asynchrones](https://docs.querying.ai/fr/concepts/async-tasks.md). Une recherche de 30 publicités se termine en général en quelques secondes, et une recherche de 500 publicités en une minute environ.

## Paramètres

* `action` : `search` (par défaut), ou `advertisers`, qui trouve des annonceurs par leur nom.
* `query` : un mot-clé. Il trouve les mots du texte d’une publicité dans n’importe quel ordre. Obligatoire sans `pageId`.
* `pageId` : l’ID numérique de la page Facebook d’un annonceur, comme `266556540473351`. Il liste les publicités de cet annonceur et, avec `query`, cherche parmi elles.
* `country` : le pays de diffusion, en code pays à deux lettres, ou `ALL` pour tous les pays. `US` par défaut.
* `activeStatus` : `active` (par défaut), `inactive` ou `all`.
* `limit` : de 1 à 500 publicités. 30 par défaut.
* `cursor` : le `nextCursor` d’une réponse précédente, pour lire les publicités suivantes.
* `searchType` : `keyword_unordered` (par défaut) ou `keyword_exact_phrase`.
* `adType` : `all` (par défaut), `political_and_issue_ads`, `housing_ads`, `employment_ads` ou `financial_products_and_services_ads`.
* `mediaType` : `all` (par défaut), `image`, `meme`, `image_and_meme`, `video` ou `none`.
* `publisherPlatforms` : une ou plusieurs valeurs parmi `facebook`, `instagram`, `audience_network`, `messenger`, `whatsapp` et `threads`, en tableau ou en texte séparé par des virgules.
* `contentLanguages` : un ou plusieurs codes de langue à deux lettres.
* `startDate`, `endDate` : `YYYY-MM-DD`. Garde les publicités affichées entre les deux dates.
* `sortBy` : `impressions_high_to_low` (par défaut) ou `most_recent`. `impressions_low_to_high` exige `adType` `political_and_issue_ads`, les seules publicités que la bibliothèque trie ainsi.

Une valeur que la bibliothèque ne peut pas rechercher est refusée avec `400 VALIDATION_ERROR`, et `details` nomme le champ.

## Lire plus de publicités

Une réponse qui laisse des publicités à lire porte `nextCursor`. Envoyez-le comme `cursor` avec la même recherche pour recevoir les publicités suivantes, de nouveau jusqu’à `limit`. Les positions reprennent après la réponse précédente, et `nextCursor` vaut `null` quand la bibliothèque n’en a plus.

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "ADS", "payload": { "platform": "meta_ad_library", "pageId": "266556540473351", "country": "US", "limit": 500, "cursor": "<nextCursor>" } }'
```

Un curseur ne sert qu’à la recherche qui l’a renvoyé : une autre valeur de `query`, `pageId`, `country`, `activeStatus` ou d’un filtre est refusée avec `400 VALIDATION_ERROR`, tandis que `limit` peut changer. Le curseur s’allonge avec les publicités lues avant lui, jusqu’à environ 14 Ko après un millier de publicités ; conservez-le comme texte sans limite de longueur. La bibliothèque liste parfois une publicité deux fois, si bien qu’une publicité peut revenir dans une réponse suivante ; `libraryId` distingue les doublons.

## Trouver un annonceur

`action` `advertisers` renvoie les pages Facebook des annonceurs dont le nom correspond à `query`, comme les suggère la barre de recherche de la bibliothèque. Envoyez le `pageId` choisi pour rechercher les publicités de cet annonceur.

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "ADS", "payload": { "platform": "meta_ad_library", "action": "advertisers", "query": "soundcore", "country": "US" } }'
```

```json theme={"theme":"css-variables"}
{
  "platform": "meta_ad_library",
  "action": "advertisers",
  "country": "US",
  "query": "soundcore",
  "returnedCount": 15,
  "advertisers": [
    {
      "position": 1,
      "pageId": "266556540473351",
      "name": "soundcore",
      "category": "Electronics",
      "likeCount": 147916,
      "verified": true,
      "country": null,
      "pageAlias": "soundcoreaudio",
      "profileUrl": "https://www.facebook.com/soundcoreaudio",
      "pictureUrl": "https://scontent-icn2-1.xx.fbcdn.net/v/t39.30808-1/793212698_1136613785698308_1883143393953135850_n.jpg",
      "instagramUsername": "soundcoreaudio",
      "instagramFollowerCount": 154040,
      "instagramVerified": true,
      "libraryUrl": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=US&is_targeted_country=false&media_type=all&search_type=page&view_all_page_id=266556540473351"
    }
  ],
  "keywords": []
}
```

Chaque annonceur comporte `position`, `pageId`, `name`, `category`, `likeCount`, `verified` (le badge bleu de Meta), `country` (le pays de la page quand Meta l’indique, comme la page britannique d’une marque mondiale), `pageAlias`, `profileUrl`, `pictureUrl`, `instagramUsername`, `instagramFollowerCount`, `instagramVerified` et `libraryUrl`, qui ouvre ses publicités dans la Bibliothèque publicitaire. `keywords` liste les recherches que la bibliothèque suggère pour ce nom. La bibliothèque cherche le nom tel que la page l’écrit : `Shokz` trouve les pages de Shokz, et `샥즈` n’en trouve aucune. Un nom qu’aucune page ne porte se termine avec `advertisers` vide. Une recherche d’annonceurs n’accepte que `query` et `country`, et coûte 0.5 crédit.

## Exemple de réponse

```json theme={"theme":"css-variables"}
{
  "platform": "meta_ad_library",
  "action": "search",
  "country": "US",
  "pageId": "266556540473351",
  "activeStatus": "active",
  "totalCount": 849,
  "returnedCount": 30,
  "hasMore": true,
  "nextCursor": "eyJ2IjoxLCJoIjoiMnhZaDJ3VVhxdGNKRXBaOSIsImMiOiJBUUhUaWVMOXYweDloLXhIYzdQV1BYSGxNcE9rcUthVVMxNnUydTNxYWpJN2FBd2lOYW8tQ0lNWm16bDE4endJcFBWViIsInMiOjAsInAiOjMwfQ",
  "libraryUrl": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&media_type=all&search_type=page&view_all_page_id=266556540473351",
  "ads": [
    {
      "position": 1,
      "libraryId": "2033461067351971",
      "libraryUrl": "https://www.facebook.com/ads/library/?id=2033461067351971",
      "pageId": "266556540473351",
      "pageName": "soundcore",
      "pageProfileUrl": "https://www.facebook.com/soundcoreaudio/",
      "pageLikeCount": 147918,
      "pageCategories": ["Electronics"],
      "isActive": true,
      "startDate": "2026-11-14",
      "endDate": "2026-11-19",
      "platforms": ["FACEBOOK", "INSTAGRAM"],
      "versions": 5,
      "format": "DCO",
      "body": "🎧Anker soundcore AeroClip 2 — the world's clearest open-ear clip-on earbuds. Now $143.99 + free earrings.",
      "title": "AeroClip 2 Open-Ear",
      "caption": "soundcore.com",
      "linkUrl": "https://www.soundcore.com/aeroclip-2-best-clear-calls-clip-on-open-earbuds-boa",
      "linkDescription": "Four colors, match.",
      "ctaText": "Shop now",
      "ctaType": "SHOP_NOW",
      "images": [],
      "videos": [],
      "cards": [
        {
          "title": "Made to Match",
          "body": "🍎Four finishes made to match. AeroClip 2, the first open-ear clip-on with Apple MFi certification.",
          "linkUrl": "https://www.soundcore.com/aeroclip-2-best-clear-calls-clip-on-open-earbuds-boa",
          "linkDescription": "Four colors, match.",
          "ctaText": "Shop Now",
          "ctaType": "SHOP_NOW",
          "imageUrl": "https://scontent-dfw6-2.xx.fbcdn.net/v/t39.35426-6/897874467_980515998005271_8997541605873239828_n.jpg"
        }
      ]
    }
  ]
}
```

## Champs du résultat

* La réponse reprend `platform`, `action`, `country`, `query` ou `pageId`, `activeStatus` et les filtres reçus.
* `totalCount` est le nombre de publicités correspondantes compté par la bibliothèque, qui l’arrondit pour les grandes recherches. `returnedCount` compte les publicités de `ads`, `hasMore` vaut `true` quand la bibliothèque en a davantage, que `nextCursor` permet de lire, et `libraryUrl` ouvre la même recherche dans la Bibliothèque publicitaire.
* Chaque publicité a `position`, `libraryId`, `libraryUrl`, `isActive`, `startDate` et `endDate` (jours en UTC), `platforms`, `versions` (le nombre de publicités qui utilisent ce contenu et ce texte), `format` (`IMAGE`, `VIDEO`, `CAROUSEL`, `DCO`, `DPA`, `MULTI_IMAGES` et d’autres), `body`, `title`, `caption`, `linkUrl`, `linkDescription`, `ctaText`, `ctaType` et `categories` (les catégories de la publicité selon la bibliothèque, comme `POLITICAL` ou `EMPLOYMENT`).
* L’annonceur est `pageId`, `pageName`, `pageProfileUrl`, `pageProfilePictureUrl`, `pageLikeCount` et `pageCategories`. Les publicités sur des sujets sociaux, des élections ou la politique ajoutent `byline`, qui a payé la publicité, et `disclaimerLabel`, et un partenariat rémunéré ajoute la page du partenaire dans `brandedContent`.
* Les médias sont `images` (`url`, `resizedUrl`), `videos` (`hdUrl`, `sdUrl`, `previewImageUrl`) et `cards`, les cartes d’une publicité carrousel ou catalogue, chacune avec ses `title`, `body`, `linkUrl`, `caption`, `linkDescription`, `ctaText`, `ctaType`, `imageUrl`, `resizedImageUrl` et `video`. Les autres textes, liens, images et vidéos d’une publicité dynamique sont dans `extraTexts`, `extraLinks`, `extraImages` et `extraVideos`.
* Les URL des médias sont des liens du CDN de Meta qui expirent au bout de quelques jours. Enregistrez les fichiers dont vous avez besoin.
* Les publicités catalogue (`DPA`, `DCO`) gardent dans leur texte les espaces réservés de la bibliothèque, comme `{{product.name}}`.
* `spend`, `currency`, `impressions` et `reach` n’apparaissent que là où la bibliothèque les publie : publicités sur des sujets sociaux, des élections ou la politique, et publicités diffusées dans l’UE.
* Une recherche sans publicité correspondante se termine avec `ads` vide et `totalCount` à `0`.

## Prix

Une recherche bloque au démarrage 0.5 crédit par tranche de 30 publicités demandées par `limit`, et coûte 0.5 crédit par tranche de 30 publicités renvoyées, avec un minimum de 0.5 crédit. La recherche par défaut de 30 publicités coûte 0.5 crédit, et une recherche avec `limit` 500 bloque 8.5 crédits. Une recherche d’annonceurs coûte 0.5 crédit. Seules les requêtes terminées sont facturées.

## Voir aussi

* [Instagram](https://docs.querying.ai/fr/engines/instagram.md)
* [Threads](https://docs.querying.ai/fr/engines/threads.md)
* [Vue d’ensemble des moteurs](https://docs.querying.ai/fr/engines/overview.md)
* [Crédits et limites](https://docs.querying.ai/fr/concepts/credits-and-limits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.