Bluesky User Posts
Bluesky User Posts 是通过账号 handle 或去中心化标识符采集的一页公开发布内容。每条标准化记录可保留帖子正文、作者身份、来源与采集时间、公开媒体、标签、提及对象和可获得的互动数量。
主要特性
- 两种账号定位方式必须且只能提交一个标识：可以是 jay.bsky.team 形式的 Bluesky handle，也可以是 did:method:identifier 形式的 DID。
- 单次一页采集对所选账号只发起一次 provider 请求，采集该源站页面公开的帖子；调用方不能设置源站 cursor 或结果数量。
- 稳定的帖子结果结构以统一字段读取帖子身份、正文、作者、时间、指标、媒体、标签和提及对象，不依赖第三方响应外层结构。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
username | 必填（至少一项） | 长度 1 到 253 的公开 Bluesky handle，只能使用字母、数字、句点或连字符，不接受开头的 @；改用 user_id 时可省略。 |
user_id | 必填（至少一项） | 以 did: 开头的 Bluesky 去中心化标识符，method 必须为小写字母或数字，后续 identifier 使用受支持的字母、数字、句点、下划线、冒号、百分号或连字符。 |
如何使用
提交 Bluesky handle 或 DID，跟踪异步任务，并在完成后读取已经保存的 PostItem 记录。
- 选择不带 @ 的公开 Bluesky handle，或者使用账号的完整 DID。
- 将所选标识 POST 到 /v1/bluesky/user-posts，并保存返回的 task_id。
- 轮询 /v1/tasks/{task_id}，直到任务成功或报告失败。
- 读取 data.results.items；仅当已保存结果还有下一页时，才继续使用任务响应里的 next_cursor。
curl -X POST "https://api.socq.ai/v1/bluesky/user-posts" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"username":"jay.bsky.team"}'
# 轮询 GET /v1/tasks/{task_id}
# 任务成功后读取 data.results.items最佳使用场景
- 账号内容快照： 为已知 handle 或 DID 保存一个时间点的一页公开帖子，并保留帖子 ID、来源 URL、发布时间和采集时间。
- 发布规律研究： 结合标准化正文、作者、标签、提及对象和可用媒体，研究所选公开账号中的主题与内容形式。
- 可见互动比较： 比较所采帖子中可获得的点赞、评论、分享和浏览数量；缺失指标应视为不可获得，而不是零。
使用建议
- handle 提交时不要带 @，并在创建任务前确认它只包含字母、数字、句点和连字符。
- 需要在 handle 变更后仍稳定定位账号时，请使用完整 DID，不要把任意用户编号当作 user_id。
- POST 请求不要添加 results_limit 或源站 cursor：provider 只采一页，且这些字段会被输入校验拒绝。
- 将作者详情、媒体、标签、提及对象和单项指标作为可空字段处理，并使用帖子 id 去重多次采集的记录。
相关 API
需要其他类型的 Bluesky 公开数据时，可以使用以下 API。
- Bluesky Profile API — 根据经过校验的 username 获取一个公开 Bluesky 主页，返回标准化身份、简介、图片、网站、状态字段、可见账号数量和采集上下文。
- Bluesky Post API — 将一个已知的公开 bsky.app 帖子 URL 解析为标准化正文、作者、媒体、时间、标签、提及和可见互动字段。