bluesky/
user-posts

通过 handle 或 DID 采集一页公开 Bluesky 帖子,返回标准化正文、作者身份、时间、互动指标和可用媒体。

Bluesky User Posts API

handle 或 DID
一页源站结果
标准化帖子记录
每次请求 0.19 积分
等待提交
等待提交

填写参数并发送请求,任务状态和标准化结果会显示在这里。

README

由 SocQ 维护 · 更新于

Bluesky User Posts

Bluesky User Posts 是通过账号 handle 或去中心化标识符采集的一页公开发布内容。每条标准化记录可保留帖子正文、作者身份、来源与采集时间、公开媒体、标签、提及对象和可获得的互动数量。

Bluesky User Posts API 主要特性

  • 两种账号定位方式必须且只能提交一个标识:可以是 jay.bsky.team 形式的 Bluesky handle,也可以是 did:method:identifier 形式的 DID。
  • 单次一页采集对所选账号只发起一次 provider 请求,采集该源站页面公开的帖子;调用方不能设置源站 cursor 或结果数量。
  • 稳定的帖子结果结构以统一字段读取帖子身份、正文、作者、时间、指标、媒体、标签和提及对象,不依赖第三方响应外层结构。

Bluesky User Posts API 参数

参数必填描述
username必填(至少一项)长度 1 到 253 的公开 Bluesky handle,只能使用字母、数字、句点或连字符,不接受开头的 @;改用 user_id 时可省略。
user_id必填(至少一项)以 did: 开头的 Bluesky 去中心化标识符,method 必须为小写字母或数字,后续 identifier 使用受支持的字母、数字、句点、下划线、冒号、百分号或连字符。

如何使用 Bluesky User Posts API

提交 Bluesky handle 或 DID,跟踪异步任务,并在完成后读取已经保存的 PostItem 记录。

  1. 选择不带 @ 的公开 Bluesky handle,或者使用账号的完整 DID。
  2. 将所选标识 POST 到 /v1/bluesky/user-posts,并保存返回的 task_id。
  3. 轮询 /v1/tasks/{task_id},直到任务成功或报告失败。
  4. 读取 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

Bluesky User Posts API 最佳使用场景

  • 账号内容快照: 为已知 handle 或 DID 保存一个时间点的一页公开帖子,并保留帖子 ID、来源 URL、发布时间和采集时间。
  • 发布规律研究: 结合标准化正文、作者、标签、提及对象和可用媒体,研究所选公开账号中的主题与内容形式。
  • 可见互动比较: 比较所采帖子中可获得的点赞、评论、分享和浏览数量;缺失指标应视为不可获得,而不是零。

Bluesky User Posts API 使用建议

  • handle 提交时不要带 @,并在创建任务前确认它只包含字母、数字、句点和连字符。
  • 需要在 handle 变更后仍稳定定位账号时,请使用完整 DID,不要把任意用户编号当作 user_id。
  • POST 请求不要添加 results_limit 或源站 cursor:provider 只采一页,且这些字段会被输入校验拒绝。
  • 将作者详情、媒体、标签、提及对象和单项指标作为可空字段处理,并使用帖子 id 去重多次采集的记录。

除了 Bluesky User Posts API,需要其他类型的 Bluesky 公开数据时,可以使用以下 API。

  • Bluesky Profile API — 根据经过校验的 username 获取一个公开 Bluesky 主页,返回标准化身份、简介、图片、网站、状态字段、可见账号数量和采集上下文。
  • Bluesky Post API — 将一个已知的公开 bsky.app 帖子 URL 解析为标准化正文、作者、媒体、时间、标签、提及和可见互动字段。

探索其他平台

还可以将 Bluesky 数据与其他已支持社交平台的公开数据结合使用。

Bluesky User Posts API — 常见问题

Bluesky User Posts API 是一个通过 Bluesky handle 或 DID 获取一页公开账号帖子的接口,返回标准化帖子正文、作者、媒体、时间和可见互动数据。

必须且只能提交一个。username 是不带 @ 的公开 handle,user_id 必须是有效 DID;同时提交两个字段会返回参数校验错误。

不可以。提交契约只接受 username 和 user_id,provider 执行也只采集一页,不会跟随第三方 cursor。

任务详情会对 SocQ 已保存的记录分页,读取 limit 可设置为 1 到 500。这个结果 cursor 不会触发新的 Bluesky provider 页面。

PostItem 包含身份、平台和资源标记、URL、发布时间与采集时间、正文、作者、指标、媒体、标签和提及对象;依赖来源的字段可能为 null。

成功任务固定消耗 0.19 个 SocQ 积分,费用不随该源站页面保存的帖子数量变化。