--- title: "Ads" description: "Facebook 광고 라이브러리를 검색하거나, 한 광고주가 집행하는 모든 광고를 가져옵니다." --- > Every apinoa docs page as markdown: https://apinoa.com/llms.txt (all in one file: https://apinoa.com/llms-full.txt; this API family in one file: https://apinoa.com/docs/social/llms.txt) ```http GET | POST /v1/facebook/ads ``` 파라미터는 `GET`의 쿼리 문자열로도, `POST`의 JSON 본문으로도 보낼 수 있습니다. 둘은 같습니다. ## 요청 ```bash tab="cURL" curl "https://gateway.apinoa.com/v1/facebook/ads?pageId=103032366405927&country=US" \ -H "x-api-key: $APINOA_API_KEY" ``` ```js tab="JavaScript" const params = new URLSearchParams({ pageId: "103032366405927", country: "US" }); const res = await fetch(`https://gateway.apinoa.com/v1/facebook/ads?${params}`, { headers: { "x-api-key": process.env.APINOA_API_KEY }, }); const { success, data, error } = await res.json(); ``` ```python tab="Python" import os import requests res = requests.get( "https://gateway.apinoa.com/v1/facebook/ads", params={"pageId": "103032366405927", "country": "US"}, headers={"x-api-key": os.environ["APINOA_API_KEY"]}, ) body = res.json() ``` ## 넘길 값 | 넘기는 값 | 읽는 것 | 비고 | |---|---|---| | `query` | 키워드에 맞는 광고 | `exact`는 구절 전체가 맞는 것만 | | `pageId` | 한 광고주가 집행하는 모든 광고 | 숫자 페이지 id. `profile`이 `id`로 돌려줍니다 | `query`나 `pageId`를 넘기세요. 필터(`country`, `status`, `adType`, `mediaType`, `platforms`, `languages`, `startDate`, `endDate`, `sort`)는 둘 다와 함께 쓸 수 있습니다. ## 파라미터 | Parameter | Type | Required | Notes | |---|---|---|---| | `adType` | enum | | all (default), or one special category: political (social issues, elections or politics), housing, employment, credit. `all` `political` `housing` `employment` `credit` | | `country` | string | | Where the ads ran: an ISO 3166-1 alpha-2 code, or ALL (default). | | `cursor` | string | | Opaque cursor from the previous page's `cursor`. Pass it alone for the next page. | | `endDate` | string | | Only ads that started running on or before this day (YYYY-MM-DD). | | `exact` | boolean | | query: match the exact phrase instead of any of its words. | | `languages` | string list | | Only ads in these languages (ISO 639-1). | | `mediaType` | enum | | all (default), image, video, meme, image_and_meme, none. `all` `image` `video` `meme` `image_and_meme` `none` | | `pageId` | string | | Every ad one advertiser runs: its numeric Page id (`profile` returns it as `id`). | | `platforms` | string list | | Only ads that ran on these platforms. | | `query` | string | | Keywords to search the Ad Library for. | | `sort` | enum | | relevance (default), or impressions (highest first; Facebook states impressions for political ads). `relevance` `impressions` | | `startDate` | string | | Only ads that started running on or after this day (YYYY-MM-DD). | | `status` | enum | | active (default), inactive or all. `active` `inactive` `all` | The same parameters, and every response type, are in the OpenAPI document: https://apinoa.com/openapi.json ## 응답 `data`에 `Ad`의 [`Page`](/docs/api-reference/sns/response-schema#page)를 돌려줍니다. 실제 응답을 줄인 것입니다. 배열은 앞쪽 항목만 남기고 긴 텍스트는 잘랐습니다. ```json { "success": true, "data": { "platform": "facebook", "items": [ { "platform": "facebook", "id": "3976964025794051", "url": "https://www.facebook.com/ads/library/?id=3976964025794051", "active": true, "startedAt": "2026-09-25T07:00:00.000Z", "endedAt": "2026-11-07T08:00:00.000Z", "platforms": [ "facebook" ], "page": { "id": "103032366405927", "name": "HOKA", "url": "https://www.facebook.com/hoka/", "avatarUrl": "https://scontent-sjc6-1.xx.fbcdn.net/v/t39.35426-6/825336657_180203818…", "likes": 1228615, "categories": [ "Outdoor & Sporting Goods Company" ] }, "format": "DPA", "title": "HOKA", "body": "You were so close to your new favorite pair of shoes.", "caption": "HOKA.COM", "linkUrl": "https://www.hoka.com/en/us/membership/?utm_source=facebookinstagram&ut…", "ctaText": "Shop now", "ctaType": "SHOP_NOW", "images": [], "videos": [], "cards": [ { "title": "HOKA", "body": "You were so close to your new favorite pair of shoes.", "caption": "hoka.com", "linkUrl": "https://www.hoka.com/en/us/womens-recovery-comfort-shoes/bondi-sr/192410928866.html", "linkDescription": "Join the HOKA® membership program for free shipping, 60 day free retur…", "ctaText": "Shop Now", "ctaType": "SHOP_NOW", "image": { "url": "https://scontent-sjc3-1.xx.fbcdn.net/v/t39.35426-6/825336518_112375061…", "resizedUrl": "https://scontent-sjc3-1.xx.fbcdn.net/v/t39.35426-6/825336518_112375061…" } } ], "ext": { "has_user_reported": false, "gated_type": "ELIGIBLE", "is_aaa_eligible": false, "regional_regulation_data": { "finserv": { "is_deemed_finserv": false, "is_limited_delivery": false }, "tw_anti_scam": { "is_limited_delivery": false } }, "hide_data_status": "NONE", "snapshot": { "is_reshared": false } } } ], "total": 76, "ext": { "pageId": "103032366405927", "searchType": "page", "countries": [ "US" ], "status": "active", "adType": "all", "mediaType": "all" }, "cursor": "wolqmF7MPrf2JKaKI1y_9VZxaa2iDzDeS7f-FTs2d0zUKqI_bJfat3T4LfV8QiVXZwwwg3…" } } ``` ## 에러 | 상태 | 코드 | 의미 | |---|---|---| | 400 | `INVALID_CURSOR` | 이 오퍼레이션이 돌려준 `cursor`가 아닙니다. `cursor` 없이 처음부터 다시 시작하세요. | | 400 | `INVALID_PARAMS` | 파라미터가 없거나, 알 수 없거나, 범위를 벗어났습니다. 메시지에 이름이 나옵니다. | | 401 | `UNAUTHORIZED` | `x-api-key` 헤더가 없거나, 폐기되었거나 알 수 없는 키입니다. | | 402 | `INSUFFICIENT_BALANCE` | 잔액이 이 호출 비용에 모자랍니다. 대시보드에서 충전하세요. | | 429 | `MARKETPLACE_SATURATED` | 동시 호출이 너무 많습니다. `Retry-After` 초만큼 기다린 뒤 다시 시도하세요. | | 502 | `UPSTREAM_ERROR` | 플랫폼이 쓸 수 없는 응답을 보냈습니다. 간격을 두고 다시 시도하세요. | 모든 코드는 [Errors](/docs/errors)에 있습니다. 실패한 호출은 과금되지 않습니다. ## 가격 **Price** $0.001 per call. [List price](https://apinoa.com/en/pricing); the rate steps down above 1,000 calls a day. ## 참고 - Facebook 전용 레코드이며, 필드는 응답에 나와 있습니다. - `total`은 맞는 광고 수를 광고 라이브러리가 밝힌 그대로 담습니다. 50,000을 넘으면 그 이상이라고만 밝히므로, 대신 `totalAtLeast`가 옵니다. - 사회 문제·선거·정치 광고(`adType=political`)에는 `spend`, `impressions`, `reach`, `currency`와 광고비를 낸 주체(`disclaimer`)도 있습니다. - 다음 페이지는 `cursor`만 넘기면 됩니다.