--- 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` 不是本操作返回的。请不带它重新开始。 | | 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`。