X Community Posts
X 社区帖子是在围绕共同主题组织的社区中发布的内容，每条帖子有作者、发布时间、正文，以及附带的图片或视频等媒体。将帖子与互动计数一起查看，可以整理具体的讨论材料，并比较组成社区公开讨论的不同帖子。
主要特性
- 读取指定社区里的帖子从社区链接开始获取该社区的公开讨论，而不是获取某个人在个人主页上发布的帖子集合。
- 为每个社区分别应用数量上限提交多个社区链接时，results_limit 会分别作用于每个社区，帖子按创建时间顺序采集，因此可以明确每个讨论空间需要获取多少内容。
- 一起保留帖子内容与必要背景每条帖子记录包含正文、作者信息、发布时间、媒体及可获取的互动计数，便于查看具体讨论，同时保留由谁发布、何时发布等背景。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
urls | 必填 | 必填公开 X 社区链接列表，链接需要包含数字社区 ID，例如 https://x.com/i/communities/1493446837214187523；在 Playground 中每行填写一条链接，代码中使用 urls 数组，不填写个人主页、搜索页或单个帖子链接。 |
results_limit | 可选 | 可选的每个社区帖子数量上限，默认 100，只接受 20 到 2000 之间的 20 倍数，例如 20、40、100；提交两个社区链接并填 20 时，每个社区分别最多提供 20 条帖子，实际数量可能更少。 |
如何使用
提交后，数据会在后台收集，因此首次响应先返回任务编号 task_id；使用这个编号查询进度，等任务完成后再读取结果。
- 复制想阅读的社区链接，并为每个社区选择 20、100 等数量上限；这里使用社区链接，不使用单个帖子 URL。
- 运行下方示例前，将 $SOCQ_API_KEY 替换为你自己的 API key，或先设置同名环境变量。按示例填写 Authorization 请求头，将 JSON 输入发送至 POST /v1/x/community-posts，并保存响应中的 task_id。
- 将保存的编号填入 GET /v1/tasks/{task_id} 查询进度。queued 表示排队，running 表示处理中，retrying 表示正在重试；等到 succeeded 再读取结果，若状态为 failed 则查看 error_message 中的失败原因。
- 任务成功后，读取 data.results.items，其中每一项描述一条社区帖子。列表为空表示任务已完成，但没有返回记录。
- 若 data.results.has_more 为 true，next_cursor 的值就是下一页结果的标记。将它原样作为 cursor 参数填入 GET /v1/tasks/{task_id}?cursor=...，继续读取直到 has_more 为 false，即可取完该任务已保存的结果。
curl -X POST "https://api.socq.ai/v1/x/community-posts" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://x.com/i/communities/1493446837214187523"],"results_limit":20}'最佳使用场景
- 准备社区讨论摘要的素材： 将取得的帖子正文、作者用户名、链接和时间整理为阅读清单，交给人工或单独的摘要工具撰写摘要，此接口负责提供帖子材料。
- 比较同一帖子的互动计数变化： 将帖子 ID、返回的计数和采集时间一起保存，在后续采集中匹配同一帖子，再自行计算已有计数的变化。
- 查看某条帖子的前后讨论： 从社区结果中选定一条帖子，把它的帖子 URL 传给 X Thread Context，继续读取与这条消息相关的公开前文和回复。
使用建议
- 为批量请求准备预算时，先用社区链接数量乘以 results_limit 估算请求记录数，再按单条帖子费率计算，不要把该上限理解为所有社区共享。
- 重复采集后追加到已保存表格之前，先按帖子 ID 匹配去重，因为同一帖子可以在后续任务中再次出现。
- 保存多个社区的结果时，将提交的社区链接与任务输入一并留存，因为标准帖子记录不保证提供可替代这部分背景的社区 ID。
相关 API
需要其他类型的 X 公开数据时，可以使用以下 API。
- Twitter Tweet Scraper API — 从 x.com 或 twitter.com status URL 获取公开帖子正文、作者、互动、媒体、标签、提及和会话关系。
- Twitter Profile Scraper API — 按 username 获取公开账号身份、简介、头像、封面、账号状态和可见受众统计。
- Twitter User Tweets Scraper API — 按 username 采集近期公开帖子、作者、媒体、标签、提及和互动指标，并排除回复。
- Twitter Search API — 按搜索表达式查找公开帖子，并支持 latest 或 top 排序和结果数量上限。
- X Followers List API — 按一个或多个 X 用户名采集公开关注者账号身份与可见资料指标。
- X Following List API — 采集 X 公开账号关注的个人资料，包括身份、简介、账号状态、可见计数和来源 username。
- X Post Quotes API — 按已知 status URL 采集公开引用帖，返回评论正文、作者、互动、媒体、时间和来源帖子上下文。
- X Post Replies API — 从 X 帖子 URL 采集公开回复，支持选择排序，并返回回复正文、作者、可见互动、媒体和父帖信息。
- X Post Retweeters API — 采集转发已知 X 或 Twitter status URL 的公开账号，并在整个任务中按账号去重后返回标准化主页记录。
- X Trends API — 按已知数字 WOEID 采集当前 X 公开趋势快照，保留来源排名、查询、描述和位置背景。
- Twitter Mentions API — 采集提及指定账号的公开帖子。
- Twitter User Search API — 按关键词查找 X 公开账号。
- X Community API — 通过社区链接读取主题说明、成员数量、规则和加入政策。
- X Thread Context API — 读取帖子及其回复链上的公开前文、后续回复和关系标识。