Ads
搜索 Facebook 广告资料库，或列出某个广告主投放的全部广告。
GET | POST /v1/facebook/ads参数可以用 GET 的查询字符串发送，也可以用 POST 的 JSON 请求体发送，两者等价。
请求
curl "https://gateway.apinoa.com/v1/facebook/ads?pageId=103032366405927&country=US" \
-H "x-api-key: $APINOA_API_KEY"传入内容
| 传入 | 读取内容 | 说明 |
|---|---|---|
query | 匹配关键词的广告 | exact 只匹配完整短语 |
pageId | 某个广告主投放的全部广告 | 数字主页 id；profile 以 id 返回 |
传入 query 或 pageId。筛选条件（country、status、adType、mediaType、platforms、languages、startDate、endDate、sort）两者都可搭配使用。
参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
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 |
这些参数及所有响应类型也写在OpenAPI 文档中。
响应
在 data 中返回 Ad 的 Page。 真实响应的节选：数组只保留前几项，长文本已截断。
{
"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。失败的调用不计费。
价格
价格 每次调用 $0.001。标价；单日调用超过 1,000 次后单价下调。
说明
- Facebook 独有的记录；其字段见响应。
total是匹配的广告数，与广告资料库所示完全一致。超过 50,000 时它只说明不少于该数，此时返回totalAtLeast。- 社会议题、选举或政治类广告（
adType=political）还带有spend、impressions、reach、currency以及出资方（disclaimer）。 - 要获取下一页，只传
cursor。