> ## 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 広告ライブラリを検索し、Facebook、Instagram、Messenger、WhatsApp、Threads に掲載中の広告を、本文、メディア、ランディングページ、掲載プラットフォームとともに JSON で受け取ります。

Meta 広告ライブラリを非同期タスク API で検索し、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/ja/concepts/async-tasks.md)を参照してください。広告 30 件の検索はたいてい数秒で、広告 500 件の検索は 1 分ほどで完了します。

## パラメータ

* `action`: `search`(デフォルト)、または名前で広告主を探す `advertisers`。
* `query`: キーワード。広告の本文に含まれる語を順序を問わず探します。`pageId` がない場合は必須です。
* `pageId`: 広告主の数字の Facebook ページ ID(例: `266556540473351`)。その広告主の広告を集め、`query` と組み合わせるとその中から検索します。
* `country`: 広告が掲載された国の 2 文字のコード、またはすべての国を表す `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` のうち 1 つ以上。配列かカンマ区切りのテキストで送ります。
* `contentLanguages`: 2 文字の言語コードを 1 つ以上。
* `startDate`、`endDate`: `YYYY-MM-DD`。2 つの日付のあいだに表示された広告を残します。
* `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 になるため、長さ制限のないテキストとして保存します。ライブラリは同じ広告を 2 回表示することがあるため、後のレスポンスに同じ広告が再び含まれることがあります。重複は `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` は、ライブラリが公開する広告にだけあります。社会問題、選挙、政治に関する広告と、EU で表示された広告です。
* 条件に合う広告がない検索は、空の `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/ja/engines/instagram.md)
* [Threads](https://docs.querying.ai/ja/engines/threads.md)
* [エンジン一覧](https://docs.querying.ai/ja/engines/overview.md)
* [クレジットと上限](https://docs.querying.ai/ja/concepts/credits-and-limits.md)


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