Skip to navigation

Read a Threads post link and save a traceable original record

To save a traceable record of one Threads post, request the full post URL with threads.web.fetch_post_detail_v2, validate and archive the raw response with archive_post.py, then split the archive with split_thread.py. The result is an archive JSON with request provenance and a SHA-256 of the source file, separate role files for the requested post, replies and thread context, and main-post-metrics.csv with the requested post’s four engagement counters.

Use one actual, complete Threads post URL. Read that one post only; the steps below do not query the post’s author or comments. Check the current price and inputs of data:threads.web.fetch_post_detail_v2 at /v1/capabilities/inspect. threads.web.fetch_post_detail_v2 accepts the URL directly in url, so no separate ID query is needed.

2. Retrieve the original details

Replace <post_url> in the request below with the post link:

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

If curl reports an HTTP error, stop and keep the error response for diagnosis. A created threads-detail.json file alone does not prove the query succeeded.

3. Validate and create an evidence archive

Save the script below as archive_post.py and run archive_post.py with Python 3. archive_post.py checks the action, the business status and data without guessing text fields, and never overwrites an existing destination file.

Before exporting, save the request you actually sent (the url parameter) and the observation time in threads-request.json, using the format below. Replace the example link and time with your recorded values. Keep the raw response threads-detail.json unchanged.

{"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. Check content and provenance

threads-archive-1.json now records the exact requested URL, the shortcode extracted from the request, the observation time, the source filename and the source file’s SHA-256. target_verification: request_manifest_only means the archive binds the source file to the recorded request; archive_post.py does not automatically match a post ID in the response. Keep the original response so the hash can be verified, and check the returned content against the requested post before using the content. The archive is an original-detail record, not a normalized CSV: BeatAPI sanitizes and passes data through directly without a uniform Threads text field. Save summaries in a separate file; do not replace source text or reconstruct missing content.

5. Bound follow-up queries

Local conversion of saved files incurs no query charge. To retrieve an author’s lists, call the matching user action with user_id; a post URL is not a user_id. The Threads user-list and search actions do not paginate, so do not loop on end_cursor. A later refresh of the post is a new query with its own snapshot and budget.

6. Verify and recover

When the response has a business failure or no data, archive_post.py creates no archive, and earlier archives stay unchanged. Before further organization, check that the archive is readable JSON, that request_id is preserved and that the target post matches. Keep the source JSON, and rerun the local script instead of querying again when a local conversion step fails.

For example, the requested post says “Trials start Monday,” and a reply says “It won’t open until Friday.” Match the requested post by the request shortcode, and cite the Friday reply separately with the reply’s source. To settle the date, look for a later announcement or a correction from the original author.

Links and IDs · Lists and pagination

7. Separate the requested post from replies and thread context

For a quote or context review, do not merge every object into “the post.” The published role-grouping description of threads.web.fetch_post_detail_v2 names a single post plus the replies, parent_thread, author_thread and pinned_replies arrays, and BeatAPI preserves all five groups under data. The requested post can itself be a reply: an is_reply flag on data.post does not move the requested post out of the main-post role.

Save the script below as split_thread.py. split_thread.py reads the validated archive, matches data.post.code against the shortcode recorded from the request, then writes one JSON file per role and a coverage report. split_thread.py keeps each object unchanged, without assuming caption is a string or borrowing Instagram text fields. When a group is missing or the main-post code differs, split_thread.py stops before creating any output.

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

Read post.json as the requested post, parent_thread.json as the context before the requested post and author_thread.json as the same author’s continuation. replies.json holds only the returned first-screen subset, not the complete discussion. pinned_replies.json can overlap replies.json, so do not add group counts together as unique commenters. The coverage report confirms the main-post code, not the truth of the post’s claims. Check each quotation in the saved object it came from, keep the author’s statements separate from your summary, and review personal information before sharing the package.

split_thread.py does not download media files, fetch more replies or query the author’s history.

8. Deliver the requested post’s engagement snapshot

The same split_thread.py run writes main-post-metrics.csv with four rows for the requested data.post only: like_count, direct_reply_count, repost_count and quote_count. Each row keeps the shortcode, the requested URL, the observation time you recorded, the request ID and the source hash recorded in the archive. When you already have the saved detail, no second API call is needed.

count keeps a reported zero as zero and stays blank for missing, null or unparsed values; state says which case applies. reported_value keeps the supplied value as JSON text for checking. Digit strings are parsed without changing their digits. Rounded labels, booleans, negative values, fractional values and integers beyond the safe numeric range are not turned into counts. reported_integer describes how the supplied value was represented; reported_integer does not verify the platform’s counting accuracy. When all four counters are unavailable, report “unavailable” rather than four zeroes.

Use main-post-metrics.csv to answer “What did this specific post report at the recorded time?” Do not add the likes of parent posts, author continuations or replies to the requested post’s likes. A requested post that is itself a reply still has its own counters. direct_reply_count is not the number of downloaded reply objects, because the returned replies group is only a first-screen subset. Keep reposts and quotes separate, and do not relabel either counter as unique people reached.

For a team handoff, deliver main-post-metrics.csv, the role files and the coverage report together with the original response and threads-request.json. State the four reported counters and any unavailable fields, and put interpretation in a separate note. A later snapshot uses a new query, a new observation time and a new output directory. Comparing two snapshots requires the same shortcode and the same metric definition, and the comparison yields a net counter change, not causal campaign lift.

The workflow follows the documented threads.web.fetch_post_detail_v2 role structure; replace the example URL and timestamp with your live request values.