Facebook Ad Library Company Ads API

Facebook Ad Library Company Ads

主要特性

• 按广告主 Page 定向采集使用一个数字广告主 Page ID，将所有返回广告限定在选定公开 Page，而不是执行关键词搜索。
• 市场与投放筛选可按国家、投放状态、媒体类型、语言、日期范围和受支持排序方式缩小保存的广告范围。
• 创意、媒体与目标链接字段为每条广告返回可用标题、正文、图片或视频、CTA、公开目标 URL 和展示格式。
• 广告主与投放上下文公开记录提供时保留 Page 身份、Page 点赞数、投放日期、活跃状态、发布平台、国家、reach、currency 和 spend。
• 限定数量的去重广告记录沿可用来源分页继续采集，按广告归档 ID 或 URL 去重，并在达到 results_limit 或最后一页时停止。

参数

如何使用

提交一个广告主 Page ID 与可选筛选条件，跟踪异步任务，再通过 cursor 分页读取标准化广告记录。

1. 获取数字广告主 Page ID，并选择所需国家、状态、媒体、语言、排序或日期筛选。
2. 将 page_id 与所选筛选条件提交到 /v1/facebook-ad-library/company-ads，并保存 task_id。
3. 轮询 /v1/tasks/{task_id}，直到任务成功或返回失败。
4. 读取 data.results.items；has_more 为 true 时，使用 next_cursor 请求下一页。

curl -X POST "https://api.socq.ai/v1/facebook-ad-library/company-ads" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page_id":"51212153078","results_limit":100,"country":"US","status":"ACTIVE","media_type":"ALL"}'

# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items，并在 has_more 为 true 时继续使用 next_cursor

最佳使用场景

• 广告主广告监测： 针对已知广告主 Page 跟踪广告归档 ID、创意文本、媒体、活跃状态、投放日期、来源 URL 和 collected_at。
• 创意与格式比较： 比较该 Page 返回广告的文本、图片或视频、展示格式、CTA、目标链接和 collation 上下文。
• 按市场筛选广告复核： 组合国家、语言、状态、媒体和日期筛选，为明确的市场或投放问题建立独立广告集合。
• 公开信号快照报告： 公开记录提供时，将 Page 身份、Page 点赞数、reach、spend、currency、投放状态和 collected_at 组合为时间点记录。

使用建议

• 先将 country 设为 ALL，并使用较宽的媒体和日期条件，再逐项收窄筛选，以便正确解释空结果。
• 验证 Page ID 与筛选组合时先使用最低 results_limit 20，确认返回范围符合任务后再增加。
• 一个 Company Ads 请求只接受一个 Page ID；品牌拥有多个广告主 Page 时应分别提交任务。
• 重复运行时按广告 id 去重，将缺失的 reach、spend、媒体和日期视为未提供而不是零，并只用 collation 字段进行分组，不据此判断表现。

相关 API