> 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.

# 公众号文章的阅读、点赞和在看怎么查？读取正文会一起返回这些数吗？

> 按公众号文章链接查阅读、点赞和在看，核对展示状态，并把多篇文章的统计整理成可复查的表。

用 **标准统计** `wechat_mp.v2.fetch_article_stats` 请求公众号文章链接，就能拿到这篇文章当前返回的阅读、点赞、在看等计数。每篇文章请求一次。标准统计不返回正文，取计数也不需要先取正文；需要正文时另用 `wechat_mp.v2.fetch_article_detail_h5` 请求。

`url` 传短式文章链接或含 `__biz` 的完整长链接都可以。保持 `raw:true`（默认值）可保留指标展示标记和取数状态；只需精简计数时传 `raw:false`。

## 按一篇文章链接取统计

```bash
curl -sS https://api.beatapi.io/v1/social-data/call \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"action":"wechat_mp.v2.fetch_article_stats","params":{"url":"<article_url>","raw":true}}' \
  -o wechat-article-stats.json
```

## 拿到数字，先看它表示什么

检查 `status:succeeded`，然后读 `data`，保留 `request_id` 和采集时间。标准统计响应里，每个计数字段要和对应标记一起读：

| 想查的指标 | 计数字段                          | 一起核对                        |
| ----- | ----------------------------- | --------------------------- |
| 阅读    | `read_num`                    | `show_read`                 |
| 点赞、在看 | `like_count`、`old_like_count` | `show_like`、`show_old_like` |
| 分享、收藏 | `share_count`、`collect_count` | `show_share`、`show_collect` |
| 评论    | `comment_count`               | `comment_enabled`           |
| 星标字段  | `star_num`                    | `show_star`，按返回字段原名保存       |

响应里有 `get_data_succ` 等取数状态时一并保留。显示「10万+」时原样记为阈值文本；返回数值 `100001` 时保留原值。字段缺失、隐藏、`null` 和查询失败分别记成四种状态；只有响应实际返回且状态可用的数字零才记为零。

只需要 H5 评论数时，请求 `wechat_mp.v2.fetch_article_stats_h5`，取 `comment_count` 和 `elected_comment_count`。已有这篇文章的 `comment_id` 就带上；`raw:true` 还能保留 `comment_raw`。`wechat_mp.v2.fetch_article_stats_h5` 不提供阅读量：H5 响应把取不到的指标列在 `unavailable`，阅读量要查标准统计。

## 同一活动的几篇文章怎么比？

先定好文章和观察时间：

1. 比较发布后第七天的数据，就在每篇文章发布满七天那天保存统计。
2. 今天一次性查三篇不同日期发布的文章时，结果标为「截至今天的累计观察」，并列出每篇的发布时间和推广条件。
3. 比较独立读者或转化时，用你有权限的账号报表核对。

每条观察保留文章链接、统计动作、指标原值、状态、采集时间和请求号。要加标题或正文，按核对过的文章身份关联[已保存的来源](/zh/faq/wechat-page-fields)。

例如同一篇文章周一、周三各取一次统计。先确认两行来自同一个文章链接和同一个统计动作，再保存两行各自的采集时间和取数状态。周三那行缺少阅读量时，保留周一的原数，变化一栏留空。

## 怎样导出小批文章核对表而不编造数值？

例如，在指定采集时间核对五篇已知活动文章的统计，并保留每个数值的确切来源。每篇一次标准统计，五篇就是五次调用，现价见[价格页](https://beatapi.io/zh/pricing)。正文和评论是另外的请求，只在需要时加。

1. 每篇文章都用前面的 curl 加 `--max-time 30` 请求，记录实际 HTTP 状态。网络超时不能证明没有扣费，所以超时的调用不要自动重试。
2. 把每次实际请求按下列格式记入 stats-pages.json。下面的 URL 和时间是占位，不是实测记录。

```json
[{"action":"wechat_mp.v2.fetch_article_stats","params":{"url":"https://mp.weixin.qq.com/s/example","raw":true},"http_status":200,"collected_at":"2026-11-16T18:00:00Z","response_file":"wechat-article-stats.json"}]
```

3. 把下面的 Python 脚本存为 wechat_metrics.py，运行 `python3 wechat_metrics.py stats-pages.json metric-review`。wechat_metrics.py 离线运行，不发收费请求。新建的 metric-review 目录包含指标行、原始响应和哈希。

```python
import csv, hashlib, json, pathlib, sys
from datetime import datetime
from urllib.parse import urlsplit, parse_qs
manifest, target = map(pathlib.Path, sys.argv[1:3])
entries = json.loads(manifest.read_text(encoding="utf-8"))
if not isinstance(entries, list) or not 1 <= len(entries) <= 100:
    raise ValueError("Supply 1–100 saved requests; no network calls are made")
STANDARD = "wechat_mp.v2.fetch_article_stats"
H5 = "wechat_mp.v2.fetch_article_stats_h5"
metrics = {"read_num": "show_read", "like_count": "show_like", "old_like_count": "show_old_like",
           "share_count": "show_share", "collect_count": "show_collect", "comment_count": "comment_enabled", "star_num": "show_star"}
rows, sources, request_ids = [], [], set()
def cell(v):
    if v is None:
        return ""
    value = str(v)
    return "'" + value if value.startswith(("=", "+", "-", "@", "\t", "\r", "\n")) else value
def classify(value, present):
    if not present:
        return "missing", None
    if value is None:
        return "null", None
    if isinstance(value, bool):
        return "invalid_boolean", None
    if type(value) is int:
        if value > 9007199254740991:
            return "unsafe_numeric", None
        return ("reported_integer", str(value)) if value >= 0 else ("invalid_negative", None)
    if isinstance(value, str):
        return ("reported_integer", value) if value.isascii() and value.isdigit() else ("reported_text", None)
    raise ValueError("Unexpected structured or floating metric")
for index, entry in enumerate(entries):
    action, params = entry["action"], entry["params"]
    if action not in (STANDARD, H5) or type(params.get("raw")) is not bool:
        raise ValueError("Use a stats action with explicit raw mode")
    allowed = {"url", "raw"} | ({"comment_id"} if action == H5 else set())
    if set(params) - allowed:
        raise ValueError("Unexpected action parameters")
    article_url = params["url"]
    if not isinstance(article_url, str) or any(c.isspace() or ord(c) < 32 for c in article_url):
        raise ValueError("Invalid public article URL")
    u = urlsplit(article_url)
    if any(k.lower() in ("key", "uin", "pass_ticket", "ticket", "access_token") for k in parse_qs(u.query, keep_blank_values=True)):
        raise ValueError("Use a public share URL without session credentials")
    if u.scheme not in ("http", "https") or u.hostname != "mp.weixin.qq.com" or u.username is not None or u.password is not None or u.port not in (None, 80, 443):
        raise ValueError("Expected original WeChat article URL")
    if u.path == "/s":
        query = parse_qs(u.query, keep_blank_values=True)
        if any(len(query.get(k, [])) != 1 or not query[k][0] for k in ("__biz", "mid", "idx")):
            raise ValueError("Long article URL needs unambiguous __biz/mid/idx")
        if not query["mid"][0].isdigit() or not query["idx"][0].isdigit() or int(query["idx"][0]) < 1:
            raise ValueError("Invalid article position")
    elif not u.path.startswith("/s/") or not u.path[3:] or "/" in u.path[3:]:
        raise ValueError("Short article URL needs a nonempty article token")
    collected = datetime.fromisoformat(entry["collected_at"].replace("Z", "+00:00"))
    if collected.tzinfo is None:
        raise ValueError("Collection time requires timezone")
    http = entry["http_status"]
    if type(http) is not int or not 100 <= http <= 599:
        raise ValueError("Record actual integer HTTP status")
    source = manifest.parent / entry["response_file"]
    raw = source.read_bytes(); result = json.loads(raw)
    evidence = {"source": str(source), "sha256": hashlib.sha256(raw).hexdigest(), "params": params,
                "action": action, "http_status": http, "collected_at": entry["collected_at"]}
    data, failure = {}, None
    if http != 200:
        error = result.get("error", {})
        if not isinstance(error, dict) or not isinstance(error.get("code"), str) or not error["code"].strip():
            raise ValueError("Expected gateway error envelope")
        request, failure = error.get("request_id"), error["code"]
    else:
        if result.get("action") != action or result.get("status") != "succeeded" or result.get("error") is not None or not isinstance(result.get("data"), dict):
            raise ValueError("Wrong action, failure or missing data object")
        request, data = result.get("request_id"), result["data"]
        if not isinstance(request, str) or not request.strip() or request in request_ids:
            raise ValueError("Missing/repeated successful request ID")
        request_ids.add(request)
    evidence.update(request_id=request, error_code=failure)
    sources.append((evidence, raw))
    unavailable = data.get("unavailable", [])
    if not isinstance(unavailable, list) or any(not isinstance(x, str) for x in unavailable):
        raise ValueError("Invalid unavailable list")
    fields = dict(metrics)
    if action == H5:
        fields["elected_comment_count"] = None
    for metric, flag in fields.items():
        raw_value = data.get(metric)
        state, value = classify(raw_value, metric in data)
        if failure:
            state, value = "gateway_failed", None
        elif metric in unavailable:
            state, value = ("unavailable" if raw_value is None else "inconsistent_unavailable"), None
        elif action == H5 and metric not in ("comment_count", "elected_comment_count"):
            state, value = "unsupported_by_action", None
        rows.append({"article_url": article_url, "action": action, "request_id": request,
                     "collected_at": entry["collected_at"], "metric": metric, "state": state, "value": value,
                     "raw_value": json.dumps(raw_value, ensure_ascii=False), "visibility_flag": flag,
                     "visibility_raw": json.dumps(data.get(flag), ensure_ascii=False) if flag else None,
                     "get_data_succ_raw": json.dumps(data.get("get_data_succ")),
                     "source_index": index + 1, "error_code": failure})
target.mkdir(exist_ok=False)
with (target / "metrics.csv").open("x", encoding="utf-8-sig", newline="") as f:
    writer = csv.DictWriter(f, fieldnames=list(rows[0])); writer.writeheader()
    writer.writerows({k: cell(v) for k, v in row.items()} for row in rows)
for index, (_, raw) in enumerate(sources):
    (target / ("raw-%03d.json" % (index + 1))).write_bytes(raw)
(target / "evidence.json").write_text(json.dumps({"requests": [x[0] for x in sources],
    "exact_audience_claim": False, "automatic_ranking": False,
    "note": "reported_integer describes syntax only; inspect source flags and platform thresholds before comparison"}, ensure_ascii=False, indent=2), encoding="utf-8")
print(json.dumps({"requests": len(sources), "metric_rows": len(rows)}))
```

导出的行这样读：

| 列或状态                  | 含义                                                   |
| --------------------- | ---------------------------------------------------- |
| value、raw_value、state | 三列分开。零保留为报告整数；缺失、null、不可得各自区分。                       |
| reported_integer      | 响应返回的是裸整数。reported_integer 只描述数值表现，不代表精确人数，也不代表指标可见。 |
| reported_text         | 「10万+」这类文本阈值。脚本不把阈值改成数字，也不把 100001 解释成十万以上。          |
| 超大整数的 value 为空        | 超过数字安全范围的裸整数不写入 value，脚本不在客户端修补。                     |
| gateway_failed        | HTTP 非 200 且带合法网关错误包装的响应；这一行保留错误证据。                  |

H5 行不会填入阅读量。表格保留原始显隐标记和取数状态，不给文章排名；比较前先看这些标记和每篇文章采集时已发布多久。

遇到 HTTP 200 的业务失败、结构异常的响应或已存在的输出目录时，wechat_metrics.py 停止且不写文件。保留原始清单和响应，用来排查停止原因。原始文件限权保存，分享时给人工复核或脱敏后的副本。前后比较要求同一文章、同一动作、同一指标口径，且采集时间可比。不要拿 H5 的 null 和标准统计值相减，也不要用阅读量推断销售。

wechat_metrics.py 接受带非空文章标识的短链，或 `__biz`、`mid`、`idx` 各有且只有一个非空值的长链。脚本拒绝带用户凭据的 URL，并原样保留文章链接。

## 十篇文章交成什么样？

十篇文章的复核交付三样东西：可比较的观察、仍待核对的文章和未决的请求尝试。

1. 计划十次标准统计请求，价格按[价格页](https://beatapi.io/zh/pricing)。
2. 导出后，选 `metrics.csv` 里 `metric=read_num` 的行，用 `article_url` 和 `source_index` 对回保存的响应。
3. 网络中断、没有响应正文的请求，单列为待核尝试。
4. 要把标题、正文和统计放进同一张表，用[来源联表](/zh/faq/wechat-page-fields)。来源联表每批最多五对，十篇分两批，每篇只放进其中一批。