跳到导航

如何从 Threads 帖子链接读取并保存可追溯原始记录?

要为一条 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> 换成帖子链接:

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 不要改写。

{"params":{"url":"https://www.threads.com/@example/post/EXAMPLE"},"collected_at":"2026-11-16T10:00:00Z"}
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)
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 · 列表与分页

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 在生成任何输出前停止。

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"]))
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 的公开角色结构设计,实际运行时请将示例链接与时间戳替换为真实请求值。