> 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 帖子链接读取并保存可追溯原始记录？

> 使用 threads.web.fetch_post_detail_v2 读取 Threads 帖子链接，通过 archive_post.py 归档原始响应与 SHA-256 来源，并用 split_thread.py 拆分角色文件与主帖互动快照 main-post-metrics.csv。

要为一条 Threads 帖子留下可追溯的原始记录，用 `threads.web.fetch_post_detail_v2` 请求完整帖子链接，用 `archive_post.py` 校验并归档原始响应，再用 `split_thread.py` 拆分归档。最终得到三类文件：带请求来源和原文件 SHA-256 的归档 JSON；主帖、回复和串上下文各自独立的角色文件；记录主帖四项互动计数的 `main-post-metrics.csv`。

## 1. 准备链接与范围

输入一条真实、完整的 Threads 帖子链接，只读这一条帖子；下面的步骤不会查询帖子作者或评论。先在 `/v1/capabilities/inspect` 免费查看 `data:threads.web.fetch_post_detail_v2` 当前的价格和参数。`threads.web.fetch_post_detail_v2` 直接在 `url` 接受链接，不需要额外查一次 ID。

## 2. 获取原始详情

把下面请求里的 `<post_url>` 换成帖子链接：

```bash
curl --fail-with-body -sS https://api.beatapi.io/v1/social-data/call \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"action":"threads.web.fetch_post_detail_v2","params":{"url":"<post_url>"}}' \
  -o threads-detail.json
```

curl 报 HTTP 错误时停止，保存错误响应以便排查。生成了 `threads-detail.json` 文件并不代表查询成功。

## 3. 校验并保存新的证据文件

把下面的脚本保存为 `archive_post.py`，用 Python 3 运行。`archive_post.py` 校验 action、业务状态和 `data`，不猜正文字段路径；目标文件已存在时拒绝覆盖。

导出前，把实际发送的请求参数（`url`）和观察时间按下面的格式保存为 `threads-request.json`。示例里的链接和时间换成你自己记录的值。原始响应 `threads-detail.json` 不要改写。

```json
{"params":{"url":"https://www.threads.com/@example/post/EXAMPLE"},"collected_at":"2026-11-16T10:00:00Z"}
```

```python
import hashlib, json, pathlib, sys
from datetime import datetime
from urllib.parse import urlsplit
source, target, manifest = map(pathlib.Path, sys.argv[1:4])
raw = source.read_bytes()
r = json.loads(raw)
if r.get("status") != "succeeded" or r.get("action") != "threads.web.fetch_post_detail_v2":
    raise ValueError("Expected successful Threads V2 detail")
if "data" not in r or r["data"] is None:
    raise ValueError("Missing detail data")
if not isinstance(r.get("request_id"), str) or not r["request_id"].strip():
    raise ValueError("Missing request_id")
request = json.loads(manifest.read_text(encoding="utf-8"))
params = request.get("params")
if not isinstance(params, dict) or set(params) != {"url"}:
    raise ValueError("Record this workflow's actual url-only request params")
url = params["url"]
parsed = urlsplit(url) if isinstance(url, str) else None
if not parsed or parsed.scheme != "https" or parsed.hostname not in {"threads.com", "www.threads.com", "threads.net", "www.threads.net"} or parsed.username:
    raise ValueError("Expected the original HTTPS Threads URL")
segments = parsed.path.strip("/").split("/")
if not (len(segments) == 3 and segments[0].startswith("@") and len(segments[0]) > 1 and segments[1] == "post" and segments[2]):
    raise ValueError("This archive example uses an @handle/post/code permalink")
stamp = request.get("collected_at")
if not isinstance(stamp, str) or datetime.fromisoformat(stamp.replace("Z", "+00:00")).tzinfo is None:
    raise ValueError("Record actual collection time with timezone")
provenance = {"params": params, "collected_at": stamp, "source_file": source.name,
              "source_sha256": hashlib.sha256(raw).hexdigest(), "requested_shortcode": segments[2],
              "target_verification": "request_manifest_only"}
with target.open("x", encoding="utf-8") as f:
    json.dump({"status":r["status"], "request_id":r.get("request_id"), "action":r["action"], "data":r["data"], "provenance":provenance},
              f, ensure_ascii=False, indent=2)
```

```bash
python3 archive_post.py threads-detail.json threads-archive-1.json threads-request.json
```

## 4. 核对来源和内容

`threads-archive-1.json` 现在记录请求的原链接、从请求提取的短代码、观察时间、原始文件名和原始文件的 SHA-256。`target_verification: request_manifest_only` 表示归档把原始文件和记录的请求绑定在一起；`archive_post.py` 不会自动匹配响应里的帖子 ID。保留原始响应以便核对哈希，使用内容前先核对返回内容就是请求的帖子。归档是原始详情记录，不是固定列的 CSV：BeatAPI 直接清洗并透传 `data`，没有统一的 Threads 正文字段。模型概括另存一个文件，不能替代原文，也不能补写缺失内容。

## 5. 继续查询的边界

对已保存文件做本地转换不产生查询费用。需要作者的列表时，用对应的用户 action 和 `user_id`；帖子链接不是 `user_id`。Threads 用户列表和搜索 action 不分页，不要围绕 `end_cursor` 循环。之后要刷新这条帖子，就是一次新查询，另存快照并单独计入预算。

## 6. 验收与恢复

响应业务失败或缺少 `data` 时，`archive_post.py` 不生成归档，已有归档保持不变。继续整理前，检查归档是可读的 JSON、`request_id` 已保留、目标帖子一致。保留源 JSON；本地转换步骤出错时重跑本地脚本，不要重新查询。

例如请求的原帖写「周一开始试用」，下方一条回复写「周五才开放」。交付时用请求短代码核对原帖，周五的说法单独引用并附上回复出处。要确认日期，查看品牌后续公告或原帖作者有没有更正。

[链接与 ID](/zh/faq/threads-link-or-id) · [列表与分页](/zh/faq/threads-lists-pagination)

## 7. 把主帖、评论与上下文拆开，避免引用错对象

做引用或上下文审阅时，不要把所有对象都混成“这条帖子”。`threads.web.fetch_post_detail_v2` 已发布的角色分组说明列出单个 `post`，以及 `replies`、`parent_thread`、`author_thread`、`pinned_replies` 四个数组；BeatAPI 在 `data` 下保留这五组。请求的帖子本身也可能是一条回复：`data.post` 上的 `is_reply` 为 true，并不会把请求帖移出主帖角色。

把下面的脚本保存为 `split_thread.py`。`split_thread.py` 读取上一步校验过的归档，把 `data.post.code` 与请求记录的短代码匹配，再按角色分别输出 JSON 文件和覆盖报告。`split_thread.py` 原样保留每个对象，不假定 `caption` 一定是字符串，也不套用 Instagram 正文字段。分组缺失或主帖短代码不一致时，`split_thread.py` 在生成任何输出前停止。

```python
import csv
import json
import sys
from pathlib import Path

source, output = map(Path, sys.argv[1:3])
archive = json.loads(source.read_text(encoding="utf-8"))
if archive.get("status") != "succeeded" or archive.get("action") != "threads.web.fetch_post_detail_v2":
    raise SystemExit("Use the validated V2 archive produced above.")
request_id = archive.get("request_id")
provenance = archive.get("provenance")
if not isinstance(request_id, str) or not request_id.strip() or not isinstance(provenance, dict):
    raise SystemExit("Missing request provenance.")
expected = provenance.get("requested_shortcode")
if not isinstance(expected, str) or not expected:
    raise SystemExit("Missing requested shortcode.")
data = archive.get("data")
if not isinstance(data, dict) or not isinstance(data.get("post"), dict):
    raise SystemExit("Expected role-grouped data.post, not a flat or filtered result.")
post = data["post"]
if post.get("code") != expected:
    raise SystemExit("Returned main post code does not match the requested shortcode.")
groups = {"post": [post]}
for role in ["replies", "parent_thread", "author_thread", "pinned_replies"]:
    value = data.get(role)
    if not isinstance(value, list) or any(not isinstance(item, dict) for item in value):
        raise SystemExit(f"Expected object array for {role}; do not manufacture missing groups.")
    groups[role] = value
report = {"request_id": request_id, "requested_url": provenance.get("params", {}).get("url"),
          "collected_at": provenance.get("collected_at"), "raw_source_sha256": provenance.get("source_sha256"),
          "matched_shortcode": expected, "target_verification": "main_post_code_matched",
          "role_counts": {role: len(items) for role, items in groups.items()},
          "scope": "one main post and the returned context; replies are a first-screen subset, not all comments",
          "counts_are": "group memberships, not distinct comments or authors"}
metric_rows = []
for field in ("like_count", "direct_reply_count", "repost_count", "quote_count"):
    value = post.get(field)
    if field not in post:
        state, count = "missing", ""
    elif value is None:
        state, count = "null", ""
    elif type(value) is int and 0 <= value <= 9007199254740991:
        state, count = "reported_integer", value
    elif isinstance(value, str) and value.isascii() and value.isdigit():
        state, count = "reported_integer", int(value)
    else:
        state, count = "unparsed_reported_value", ""
    metric_rows.append({"code": expected, "metric": field, "count": count, "state": state,
                        "reported_value": json.dumps(value, ensure_ascii=False) if field in post else "",
                        "requested_url": report["requested_url"], "collected_at": report["collected_at"],
                        "request_id": request_id, "raw_source_sha256": report["raw_source_sha256"]})
report["main_post_metrics"] = {row["metric"]: row["state"] for row in metric_rows}
report["integer_metrics_available"] = sum(row["state"] == "reported_integer" for row in metric_rows)
output.mkdir(exist_ok=False)
for role, items in groups.items():
    (output / (role + ".json")).write_text(json.dumps(items, ensure_ascii=False, indent=2), encoding="utf-8")
with (output / "main-post-metrics.csv").open("x", encoding="utf-8-sig", newline="") as handle:
    writer = csv.DictWriter(handle, fieldnames=list(metric_rows[0]))
    writer.writeheader()
    for row in metric_rows:
        writer.writerow({key: ("'" + value if isinstance(value, str) and value.lstrip().startswith(("=", "+", "-", "@")) else value) for key, value in row.items()})
(output / "report.json").write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
print(json.dumps(report["role_counts"]))
```

```bash
python3 split_thread.py threads-archive-1.json thread-review
```

把 `post.json` 当作请求的帖子，`parent_thread.json` 是请求帖之前的父帖上下文，`author_thread.json` 是同一作者继续发布的串。`replies.json` 只是返回的首屏子集，不是完整讨论；`pinned_replies.json` 可能和 `replies.json` 重叠，不能把各组数量相加当独立评论人数。覆盖报告确认的是主帖短代码，不是帖子陈述是否属实。每条引文都应回到对应已保存对象中核对原文，作者陈述与自己的总结分开写；分享资料包前检查个人信息。

`split_thread.py` 不会下载媒体文件、补抓更多回复或查询作者历史。

## 8. 交付所请求帖子的互动快照

同一次 `split_thread.py` 运行还会生成 `main-post-metrics.csv`，只取请求的 `data.post`，固定四行：`like_count`、`direct_reply_count`、`repost_count`、`quote_count`。每行保留短代码、请求 URL、你记录的观察时间、request_id 和归档里记录的原文哈希。已经保存详情时，不需要再调用 API。

`count` 把报告值 0 保留为 0，缺失、null 或无法解析的值留空，`state` 说明属于哪种情况。`reported_value` 用 JSON 文本保留提供的原值以供核对。数字字符串按原数字解析，不改动数字。缩略标签、布尔值、负数、小数和超出安全范围的大整数不会被转换成计数。`reported_integer` 只说明原值的表示形式，并不验证平台计数是否准确。四项都不可得时，报告“不可得”，不要填四个零。

`main-post-metrics.csv` 回答的是“这条具体帖子在记录时间报告了多少互动”。不要把父帖、作者后续串或回复的点赞加到请求帖的点赞里。请求帖本身是一条回复时，也只读请求帖自己的计数。`direct_reply_count` 不等于已下载的回复对象数量，因为返回的 `replies` 只是首屏子集。转发数和引用数分开保留，都不能改称独立触达人数。

交给团队时，把 `main-post-metrics.csv`、各角色文件和覆盖报告，与原始响应、`threads-request.json` 一起交付。写明四项报告计数和缺失项，解读另写一份说明。之后再观察时，使用新的查询、新的观察时间和新的输出目录。比较两次快照必须使用相同短代码和相同指标定义，差值只是计数净变化，不证明投放带来的提升。

本流程依据 `threads.web.fetch_post_detail_v2` 的公开角色结构设计，实际运行时请将示例链接与时间戳替换为真实请求值。