> ## 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.

# Meta 广告资料库 API

> 按关键词或广告主搜索 Meta 广告资料库，以 JSON 获取正在 Facebook、Instagram、Messenger、WhatsApp 和 Threads 上投放的广告，包含文案、媒体、落地页和投放平台。

通过异步任务 API 搜索 Meta 广告资料库，并以 JSON 获取结果。发送 `taskType` `ADS` 并设置 `platform` `meta_ad_library`，在 `query` 中填入关键词，或在 `pageId` 中填入广告主的 Facebook 主页 ID。搜索按返回的**每 30 条广告 0.5 积分**计费。如需按名称查找广告主的主页 ID，请发送 `action` `advertisers`。

## 请求

```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" } }'
```

提交任务后，轮询 `GET /v1/async/task/{id}` 或通过 webhook 接收。参见[异步任务](https://docs.querying.ai/zh/concepts/async-tasks.md)。30 条广告的搜索通常几秒内完成，500 条广告的搜索约需一分钟。

## 参数

* `action`：`search`（默认），或按名称查找广告主的 `advertisers`。
* `query`：关键词。按任意顺序匹配广告文案中的词语。未设置 `pageId` 时必填。
* `pageId`：广告主的数字 Facebook 主页 ID，例如 `266556540473351`。列出该广告主的广告，与 `query` 一起使用时在其中搜索。
* `country`：广告投放国家的两字母代码，或表示所有国家的 `ALL`。默认 `US`。
* `activeStatus`：`active`（默认）、`inactive` 或 `all`。
* `limit`：1 到 500 条广告。默认 30。
* `cursor`：之前响应中的 `nextCursor`，用于继续获取其后的广告。
* `searchType`：`keyword_unordered`（默认）或 `keyword_exact_phrase`。
* `adType`：`all`（默认）、`political_and_issue_ads`、`housing_ads`、`employment_ads` 或 `financial_products_and_services_ads`。
* `mediaType`：`all`（默认）、`image`、`meme`、`image_and_meme`、`video` 或 `none`。
* `publisherPlatforms`：`facebook`、`instagram`、`audience_network`、`messenger`、`whatsapp` 和 `threads` 中的一个或多个，以数组或逗号分隔的文本发送。
* `contentLanguages`：一个或多个两字母语言代码。
* `startDate`、`endDate`：`YYYY-MM-DD`。保留在这两个日期之间展示过的广告。
* `sortBy`：`impressions_high_to_low`（默认）或 `most_recent`。`impressions_low_to_high` 只能与 `adType` `political_and_issue_ads` 一起使用，资料库只对这类广告按此顺序排序。

资料库无法搜索的值会以 `400 VALIDATION_ERROR` 拒绝，`details` 会指出该字段。

## 继续获取广告

还有广告可获取时，响应会带有 `nextCursor`。在同一搜索中把它作为 `cursor` 发送，即可再获取最多 `limit` 条后续广告。`position` 接着上一次响应编号，资料库没有更多广告时 `nextCursor` 为 `null`。

```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>" } }'
```

游标只能用于返回它的那次搜索：`query`、`pageId`、`country`、`activeStatus` 或筛选条件不同会以 `400 VALIDATION_ERROR` 拒绝，`limit` 可以更改。游标随之前读取的广告增多而变长，读取 1,000 条广告后约为 14 KB，请以不限长度的文本保存。资料库有时会把同一条广告列出两次，因此后续响应中可能再次出现同一条广告，可用 `libraryId` 区分重复。

## 查找广告主

`action` `advertisers` 会像广告资料库搜索框的建议那样，返回名称与 `query` 匹配的广告主 Facebook 主页。用选中广告主的 `pageId` 搜索其广告。

```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": []
}
```

每个广告主包含 `position`、`pageId`、`name`、`category`、`likeCount`、`verified`（Meta 蓝色认证标志）、`country`（Meta 标明主页国家时提供，例如全球品牌的英国主页）、`pageAlias`、`profileUrl`、`pictureUrl`、`instagramUsername`、`instagramFollowerCount`、`instagramVerified`，以及在广告资料库中打开该广告主广告的 `libraryUrl`。`keywords` 是资料库为该名称建议的搜索词。资料库按主页上写的名称匹配，所以 `Shokz` 能找到 Shokz 的主页，`샥즈` 则找不到。没有匹配的主页时以空的 `advertisers` 完成。广告主搜索只接受 `query` 和 `country`，消耗 0.5 积分。

## 响应示例

```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"
        }
      ]
    }
  ]
}
```

## 结果字段

* 响应原样返回 `platform`、`action`、`country`、`query` 或 `pageId`、`activeStatus` 以及传入的筛选条件。
* `totalCount` 是资料库统计的符合条件的广告数，大型搜索的数量由资料库取整。`returnedCount` 是 `ads` 中的广告数，资料库还有更多广告时 `hasMore` 为 `true`，可用 `nextCursor` 继续获取，`libraryUrl` 在广告资料库中打开同一搜索。
* 每条广告包含 `position`、`libraryId`、`libraryUrl`、`isActive`、`startDate` 和 `endDate`（UTC 日期）、`platforms`、`versions`（使用同一素材和文案的广告数）、`format`（`IMAGE`、`VIDEO`、`CAROUSEL`、`DCO`、`DPA`、`MULTI_IMAGES` 等）、`body`、`title`、`caption`、`linkUrl`、`linkDescription`、`ctaText`、`ctaType` 和 `categories`（资料库对广告的分类，例如 `POLITICAL` 或 `EMPLOYMENT`）。
* 广告主信息是 `pageId`、`pageName`、`pageProfileUrl`、`pageProfilePictureUrl`、`pageLikeCount` 和 `pageCategories`。社会议题、选举或政治广告会加上出资方 `byline` 和 `disclaimerLabel`，付费合作广告会在 `brandedContent` 中加上合作方主页。
* 媒体是 `images`（`url`、`resizedUrl`）、`videos`（`hdUrl`、`sdUrl`、`previewImageUrl`）和 `cards`。`cards` 是轮播广告或目录广告的卡片，每张卡片都有 `title`、`body`、`linkUrl`、`caption`、`linkDescription`、`ctaText`、`ctaType`、`imageUrl`、`resizedImageUrl` 和 `video`。动态广告的其他文案、链接、图片和视频在 `extraTexts`、`extraLinks`、`extraImages` 和 `extraVideos` 中。
* 媒体 URL 是几天后失效的 Meta CDN 链接，请保存需要的文件。
* 目录广告（`DPA`、`DCO`）的文案会保留资料库的占位符，例如 `{{product.name}}`。
* `spend`、`currency`、`impressions` 和 `reach` 只出现在资料库公开这些数据的广告中：社会议题、选举或政治广告，以及在欧盟展示的广告。
* 没有符合条件的广告时，搜索以空的 `ads` 和 `totalCount` `0` 完成。

## 价格

搜索开始时按 `limit` 请求的每 30 条广告冻结 0.5 积分，并按返回的每 30 条广告扣除 0.5 积分，最少 0.5 积分。默认搜索（30 条广告）消耗 0.5 积分，`limit` 为 500 的搜索冻结 8.5 积分。广告主搜索消耗 0.5 积分。只对完成的请求计费。

## 相关

* [Instagram](https://docs.querying.ai/zh/engines/instagram.md)
* [Threads](https://docs.querying.ai/zh/engines/threads.md)
* [引擎概览](https://docs.querying.ai/zh/engines/overview.md)
* [积分与限制](https://docs.querying.ai/zh/concepts/credits-and-limits.md)


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