> ## 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 광고 라이브러리를 비동기 task 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" } }'
```

task를 제출한 뒤 `GET /v1/async/task/{id}`를 폴링하거나 웹훅으로 받습니다. 참고: [비동기 task](https://docs.querying.ai/ko/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` 중 하나 이상. 배열이나 쉼표로 구분한 텍스트로 보냅니다.
* `contentLanguages`: 2글자 언어 코드 하나 이상.
* `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개 뒤에는 약 14KB이므로, 길이 제한 없는 텍스트로 저장합니다. 라이브러리가 같은 광고를 두 번 보여 줄 때가 있어 다음 응답에 같은 광고가 다시 올 수 있습니다. 중복은 `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/ko/engines/instagram.md)
* [Threads](https://docs.querying.ai/ko/engines/threads.md)
* [엔진 목록](https://docs.querying.ai/ko/engines/overview.md)
* [크레딧과 한도](https://docs.querying.ai/ko/concepts/credits-and-limits.md)


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