Facebook Scraper：主页帖子与广告库采集

集为异步**：提交 run → 轮询状态 → 取数，端到端流程见 快速开始；统一响应信封、run 状态机、计费与错误码见 认证与错误处理。本文只列 Facebook 各端点的提交路径、target 字段与输出字段。

端点总览

通用请求头：

Authorization: Bearer ants_xxxxxxxxxxxx
Content-Type: application/json

提交体统一为 { "deliveryMode": "async", "recordLimit": 1000, "targets": [ … ] }：recordLimit 控制每个 target 的记录上限，targets 里每个元素的字段见下方各端点。

💡 也可用 deliveryMode: "sync" 同步模式（小任务阻塞等终态，超时自动 fallback 转轮询）——详见 快速开始 · 同步模式。

主页帖子 — Page Posts

采集一个或多个 Facebook 主页的帖子，含正文、发布时间、互动、附件与评论。

端点： POST /v1/scraper/facebook/page-posts

target 字段（targets[] 每个元素）：

每主页的帖子数上限亦可由提交体顶层 recordLimit 控制（见 快速开始）。

输出字段（records 里每条记录）：

提交示例：

curl -X POST "https://api.antsdata.com/v1/scraper/facebook/page-posts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryMode": "async",
    "recordLimit": 1000,
    "targets": [
      { "pageUrls": "[\"https://facebook.com/nike\"]", "since": "2026-01-01", "includeComments": true, "commentsLimit": 20 },
      { "pageIds": "[\"15087023444\"]" }
    ]
  }'

提交成功返回 HTTP 201 + 任务号，status 为 queued：

{ "code": 0, "message": "ok", "data": { "id": 1287346, "status": "queued" } }

随后按 id 轮询 GET /v1/scraper/runs/{id} 至 succeeded，再取记录或下载——完整轮询与取数流程见 快速开始。

广告库 — Ads Library

检索 Facebook 广告库中正在或曾经投放的广告，按关键词、国家/地区、类型等条件筛选。一个 target = 一次检索。

端点： POST /v1/scraper/facebook/ads-library

target 字段（targets[] 每个元素 = 一次检索）：

countries 必填（至少一个国家码）以圈定检索范围；search_terms / ad_type 等为可选筛选。返回的广告数上限由提交体顶层 recordLimit 控制。

输出字段（records 里每条记录）：

提交示例：

curl -X POST "https://api.antsdata.com/v1/scraper/facebook/ads-library" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryMode": "async",
    "recordLimit": 1000,
    "targets": [
      {
        "countries": ["US", "GB"],
        "search_terms": ["nike"],
        "ad_type": "ALL",
        "active_status": "active",
        "start_date": "2026-05-01",
        "end_date": "2026-06-30"
      }
    ]
  }'

提交成功返回 HTTP 201 + 任务号，status 为 queued：

{ "code": 0, "message": "ok", "data": { "id": 1287347, "status": "queued" } }

随后按 id 轮询 GET /v1/scraper/runs/{id} 至 succeeded，再取记录或下载——见 快速开始。

取数与错误

• 取数：run 到 succeeded 后，GET /v1/scraper/runs/{id}/records?page=1&pageSize=20 分页取记录，或 GET /v1/scraper/runs/{id}/download?format=json|csv|excel 下载整份产物。
• 进度与逐目标结果：轮询 run 对象的 targetsOk / targetsFailed 看进度；单个主页 / 检索失败不影响整 run，失败细节在 tasks[].errorMessage。
• 计费：按成功产出的数据条数结算；全部目标失败释放冻结、不计费。
• 错误：整请求错误返回对应 HTTP 状态码 + { "code": <int>, "message": <msg> }（如积分不足 402、限流 429 + Retry-After）。

信封、状态机、计费与完整错误码见 认证与错误处理。

FAQ

Q: 一次能采集多个主页吗？

可以。targets 是数组，一个 run 可含多次检索；单个 target 的 pageUrls / pageIds 本身也可携带多个主页。逐目标状态见 run 对象的 tasks[]。

Q: 提交后为什么没有直接返回帖子 / 广告数据？

采集是异步的：提交拿任务 id，后台执行，你轮询 id 到 succeeded 后再按 id 取记录或下载。

Q: 广告库检索必须填哪些字段？

countries 必填（至少一个国家码）以圈定检索范围，search_terms / ad_type 等为可选筛选。

Q: 采集失败会扣费吗？

不会。全部目标失败释放冻结、不计费；部分成功只按成功产出的条数结算。详见 认证与错误处理。

下一步

• 平台指南：TikTok · X · Instagram · LinkedIn · Google · YouTube · Amazon
• 同步搜索：Google SERP
• 认证与错误处理 — 统一响应信封、run 状态机、计费与错误码