Facebook Posts
Facebook Posts 是 Page、个人主页或群组发布的公开动态，包含文本、链接、媒体、作者信息、发布时间和可见互动。这些内容与互动信号可用于活动监测、编辑研究、受众分析和报表制作。
主要特性
- 支持的公开 URL通过统一响应结构采集 Facebook 公开 Page、个人主页、群组或帖子 URL 对应的帖子。
- 内容与媒体字段以标准化字段返回帖子文本、post ID、作者信息、发布时间、链接、媒体、分享数、评论数和可见 reaction 计数。
- 表情回应明细提供 like、love、wow、care、sad、angry 和 haha 等可见 reaction 明细。
- 请求结果上限接受一个或多个受支持的 URL，并用 results_limit 限制请求的帖子记录数。
- 公开数据边界响应边界限定在公开结果内，不覆盖私密、受限、登录后可见或已删除内容。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
urls | 必填 | 公开 Facebook 公共主页、个人主页、小组或帖子 URL，多个值使用逗号或换行分隔。 |
results_limit | 可选 | 采集任务请求的最大记录数，必须为正整数。 |
如何使用
先提交异步采集任务，轮询 task ID，任务完成后再用 cursor 分页读取标准化公开帖子结果。
- 准备一个或多个 Facebook 公开 Page、profile、group 或 post URL。
- 向 /v1/facebook/posts POST urls 和可选的 results_limit。
- 轮询 /v1/tasks/{task_id}，直到状态变为 succeeded 或 failed。
- 通过 /v1/tasks/{task_id}?limit=50 读取 data.results，有更多记录时继续传 results.next_cursor。
curl -X POST "https://api.socq.ai/v1/facebook/posts" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://www.facebook.com/cern"],"results_limit":25}'
# 轮询 GET /v1/tasks/{task_id}，再读取 /v1/tasks/{task_id}?limit=50，并使用 data.results。最佳使用场景
- 公开页面监控： 收集产品需要跟踪的 Facebook 公开页面帖子、发布时间、链接、媒体引用和可见计数。
- 活动和品牌报表： 把帖子文本、reaction、评论数、分享数和媒体字段标准化后，再写入活动看板或 BI 工具。
- 内容研究： 围绕品牌、事件或主题分析公开 caption、帖子话题、链接、图片、视频和互动模式。
- Social listening 工作流： 把公开帖子信号接入审核队列、告警系统或内部研究工具，而不是在业务代码里维护脆弱的页面解析器。
- 帖子归档和审计： 保存标准化 post ID、来源 URL、发布时间、可见计数和采集时间，用于构建可复核的归档与报表。
使用建议
- 先用较小的公开页面批次测试，确认重试和 backoff 行为稳定后再提高 limit。
- 保存标准化 post ID、URL、task ID 和 next_cursor，方便失败后继续采集。
- 有些公开帖子可能不会暴露评论、媒体、reaction 明细或发布时间，客户端需要能处理字段缺失。
- 如果需要更深的公开评论线程，请使用 Comments API，而不是只依赖轻量 comments_preview。
- 不要默认这个接口能读取私密、受限、登录后可见或账号自有数据，除非公开 API 文档明确支持。
相关 API
需要其他类型的 Facebook 公开数据时，可以使用以下 API。
- Facebook Pages API — 获取公开 Page 资料、联系方式、图片和可见受众评分。
- Facebook Comments API — 从帖子 URL 采集公开评论、作者、互动、媒体和来源链接。
- Facebook Video Transcript API — 从已知的公开视频帖子或 Reel URL 提取可用字幕文本和格式。
- Facebook Group Posts API — 从 Facebook 群组 URL 采集公开帖子，可选择排序并设置每个群组的数量上限，返回作者、视频媒体和可见互动信息。
- Facebook Events Search API — 按关键词搜索公开活动，返回日程、地点、出席指标、封面媒体和活动状态字段。
- Facebook Ad Transcript API — 从 Facebook Ad Library URL 提取可用口播文本、语言、格式和来源上下文。
- Facebook Comment Replies API — 使用已知评论的 feedback ID 和 expansion token 获取公开回复，返回文本、作者标识、互动指标和父级上下文。
- Facebook Company Reviews API — 采集公开 Page 评价，返回评价文本、评价者链接、评分、点赞数、时间和公司上下文。
- Facebook Event Details API — 通过已知公开活动 URL 采集标准化元数据、日程、地点、媒体和可见互动指标。
- Facebook Profile Events API — 从个人资料或 Page URL 采集关联的公开活动，返回名称、日程、地点、媒体、可见指标和来源上下文。
- Facebook Profile Photos API — 从个人资料或 Page URL 采集公开照片，返回说明文字、作者上下文、互动指标、图片元数据和来源引用。
- Facebook Profiles API — 通过已知 Facebook URL 查询公开个人资料或主页，返回身份信息、简介、头像、可见计数和输入上下文。
- Facebook Reels API — 从个人资料或 Page URL 采集公开 Reels，返回说明文字、作者上下文、视频元数据、可见互动和来源引用。