> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# Threads 帖子链接、短代码和数字 ID 分别用哪个接口？

> 调用 threads.web.fetch_post_detail_v2 时在 url 传入完整帖子链接或在 post_id 传入短代码，数字帖子 ID 仅用于旧接口 threads.web.fetch_post_detail，主帖正文与互动数均位于 data.post。

把完整的 Threads 帖子链接放进 `url`，或把帖子短代码放进 `post_id`，调用 `threads.web.fetch_post_detail_v2`。短代码是链接里 `/post/` 后面的部分。只有旧接口 `threads.web.fetch_post_detail` 要数字帖子 ID。V2 返回里，`data.post` 就是你请求的帖子，这条帖子自己的互动数也在 `data.post` 下。

## 有完整帖子链接，是否需要先买一次 ID 解析？

不需要。把完整链接放进 `threads.web.fetch_post_detail_v2` 的 `url`。`threads.web.fetch_post_detail_v2` 也接受 `post_id`，V2 的 `post_id` 是链接 `/post/` 后的短代码，不是旧接口要求的数字 ID。只提供一种已知标识，不要同时给出指向不同帖子的 `url` 和 `post_id`。

## 旧详情接口的 post_id 是同一个字段吗？

不是。`threads.web.fetch_post_detail` 的 `post_id` 要数字帖子 ID；`threads.web.fetch_post_detail_v2` 的 `post_id` 是短代码。两个接口参数名相同，含义不同。用户主页的 @username 既不是数字帖子 ID，也不是短代码。作者数字 ID 用于用户帖子和用户回复列表，不用于帖子详情。

## 为什么旧目录有带空格的 action？

旧目录里 `fetch_post_comments` 和 `search_profiles` 两项曾带尾随空格。BeatAPI 会自动去除公开 action 名称的首尾空格，并同时支持无空格的规范名称与旧别名。新请求中不要复制尾随空格，调用前先查阅公开接口文档确认该 action 可用。归档流程使用 `threads.web.fetch_post_detail_v2`，不依赖旧评论接口。

## 哪个分组才是我请求的主帖？

`threads.web.fetch_post_detail_v2` 按角色分组返回。`data.post` 是当前请求的帖子，另外四个上下文数组是 `replies`、`parent_thread`、`author_thread`、`pinned_replies`。`replies` 只是首屏返回的回复子集，不是全部讨论。

把 `data.post.code` 和请求的短代码对上。请求的帖子本身也可能是一条回复，所以 `data.post` 带 `is_reply: true` 时，不能将 `data.post` 判为另一条目标帖下的评论。Threads 帖子归档指南提供按 V2 返回结构核对过的角色拆分校验。

## 返回后从哪里读取？

1. 检查 `status=succeeded`。
2. 保存 `request_id` 和 `data`。BeatAPI 直接清洗并透传 `data`，没有统一的 Threads `post.text` 字段。
3. 按原样归档 `data` 对象。不要套用 Instagram 或 X 的字段路径，缺失的正文不让模型补写。

同事贴来一条回复链接时，先确认回复的短代码和返回的 `data.post.code` 一致。引用这条回复本身时取 `data.post`；要交代这条回复在回应什么，看同一响应里的 `parent_thread`。

[读取并保存帖子](/zh/guides/threads-post-archive)

## 哪些互动数才属于我请求的帖子？

读取 `data.post` 下的 `like_count`、`direct_reply_count`、`repost_count`、`quote_count`，不要把四个上下文数组的计数相加。归档指南的角色拆分脚本将 `like_count`、`direct_reply_count`、`repost_count`、`quote_count` 导出到 `main-post-metrics.csv`，同时保留请求和观察时间来源。Threads 响应不包含 `metrics.views` 或 `metrics.shares` 字段。

`direct_reply_count` 可以大于 `replies` 里的对象数，因为 `replies` 只是子集。缺失不是零，引用数和转发数分开记。请求的帖子本身是一条回复时，`data.post` 下的计数仍属于这条请求帖。`main-post-metrics.csv` 记录的是观察时间点的计数快照，不能衡量触达、独立评论者数量或投放效果。