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

# 选小红书合作博主时，怎样看自然阅读和全部阅读？

> 从博主合作评估出发，选择自然或全部流量，分清合作笔记与推广流量，再按同篇内容比较和复盘。

想只看小红书博主笔记的自然阅读，在蒲公英核心数据 `xiaohongshu.pgy.get_blogger_core_data` 或笔记案例 `xiaohongshu.pgy.get_blogger_notes` 的请求里把 `advertise_switch` 设为 `0`。要看包含推广的全部流量，设为 `1`。内容类型和日常/合作口径用其他参数另外选。

例如挑三位咖啡教程博主，三位都用同一种图文或视频形式、同一观察周期和同一流量口径。要比较同一篇笔记的自然阅读和全部阅读，用 `noteId` 对齐两份结果，并保留各自的采集时间。

## 这次该取哪一种数据？

| 要回答的问题                | 选择与用法                    |
| --------------------- | ------------------------ |
| 博主近期的日常或合作内容表现怎样？     | 用核心数据，统一周期、图文/视频及自然/全部口径 |
| 哪些具体教程值得作为合作参考？       | 用笔记案例页，选择自然口径，结合内容逐篇看    |
| 同一篇笔记在自然与全部口径下报告多少阅读？ | 分别保存两份案例页，按笔记ID对齐后比较     |
| 这个项目的推广投入带来多少效果？      | 再结合项目自己的投放与结案报告，使用一致统计口径 |

“合作笔记”说的是内容的合作属性，不代表一定有推广流量；日常内容也不能凭分类认定没有推广。所以筛选“合作”之后，还要用 `advertise_switch` 另外选择自然或全部口径。

## 先看一份统一口径的核心数据

下面的请求用 `xiaohongshu.pgy.get_blogger_core_data` 取指定博主近30日、图文加视频、合作笔记、自然口径的核心数据，给候选评估补一个周期观察：

```bash
curl -sS https://api.beatapi.io/v1/social-data/call \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"action":"xiaohongshu.pgy.get_blogger_core_data","params":{"user_id":"<user_id>","business":1,"advertise_switch":0,"date_type":1,"note_type":3}}' \
  -o creator-organic-cooperation.json
```

| 核心数据字段             | 选项             |
| ------------------ | -------------- |
| `business`         | 0 日常，1 合作      |
| `advertise_switch` | 0 自然，1 全部      |
| `date_type`        | 1 近30日，2 近90日  |
| `note_type`        | 1 图文，2 视频，3 两者 |

逐篇案例用 `xiaohongshu.pgy.get_blogger_notes`，案例列表的 `note_type` 是 4 全部、3 合作、1 图文、2 视频。每个动作按自己的取值填写，不要把核心数据的“3 两者”误填成案例列表的“3 合作”。

## 两种阅读拿到以后怎样用？

先按 `noteId` 匹配同一篇笔记，保留两次观察的时间，再比较 `readNum`。**示意**：一篇教程自然阅读 1000、全部阅读 1600，表中记录观察差值 600，并附两次来源；结论写成“本次两种口径有差异，值得结合项目资料继续看”。

如果自然阅读有 1000，而全部口径的页面里没有这篇，标为“另一页未匹配”，不填 0。两页都按阅读排序时可能选出不同的笔记，所以比较同一篇内容时按最新排序、其余条件不变，并保留没匹配上的笔记。

选合作博主时，先看相关教程是否持续提供有用内容，再结合可比的自然阅读和[受众情况](/zh/faq/xiaohongshu-audience-quality)写候选理由。做结案时，观察差值与项目报告分列；两次采集有时间差，聚合的中位数、比例也不能当成逐篇阅读数相减。

把任务交给已接入工具的助手时，可以这样写：

> 为这三位咖啡教程博主整理合作参考。统一时间、内容形式和流量口径，先看相关教程的自然阅读与内容。若已有自然/全部两份案例页，按笔记ID配对，保留时间和未匹配项，列出值得进一步读的内容及候选理由。

下面的本地比较器 compare_pgy_scopes.py 把已保存的两份案例页转成可回查的逐篇表。

## 两份笔记页怎么对比，而不编造推广归因？

逐篇比较用 xiaohongshu.pgy.get_blogger_notes，不用博主汇总数据。已核对的返回说明明确有 data.data.list\[].noteId 和 readNum。两次请求用同一博主、笔记类型、页码和页大小，按最新排序 order_type:1，只改 advertise_switch。按阅读排序时，口径一变样本就换，不能当作匹配名单；即使按最新排序，两次调用之间也可能变化，所以按真实笔记 ID 对齐，并保留未匹配项。

当前单价见[价格页](https://beatapi.io/zh/pricing)。两种口径各取一页就是两次案例页查询；已有原件直接复用。保存真实响应，并在下面的清单里填实际采集时间：

```json
[{"action":"xiaohongshu.pgy.get_blogger_notes","params":{"user_id":"YOUR_VERIFIED_USER_ID","note_type":3,"order_type":1,"advertise_switch":0,"page_number":1,"page_size":8},"collected_at":"2026-11-16T10:00:00Z","response_file":"organic.json"},{"action":"xiaohongshu.pgy.get_blogger_notes","params":{"user_id":"YOUR_VERIFIED_USER_ID","note_type":3,"order_type":1,"advertise_switch":1,"page_number":1,"page_size":8},"collected_at":"2026-11-16T10:01:00Z","response_file":"all.json"}]
```

把下面的脚本保存为 compare_pgy_scopes.py。脚本检查已保存的结果是否业务成功，拒绝筛选条件不一致和单页内重复的笔记 ID，按笔记 ID 并集输出匹配/缺失覆盖。compare_pgy_scopes.py 不请求 API。

```python
import csv,datetime,hashlib,json,pathlib,sys
manifest,target=map(pathlib.Path,sys.argv[1:3])
entries=json.loads(manifest.read_text(encoding="utf-8"))
if not isinstance(entries,list) or len(entries)!=2:raise ValueError("Exactly one organic and one all-traffic saved request required")
scopes={};base=None;request_ids=set()
for entry in entries:
    if entry.get("action")!="xiaohongshu.pgy.get_blogger_notes":raise ValueError("Use note cases, not aggregate metrics")
    params=entry["params"]
    allowed={"user_id","note_type","order_type","advertise_switch","page_number","page_size","feature_tag","content_tag","is_third_platform"}
    if not isinstance(params,dict) or set(params)-allowed:raise ValueError("Use only documented input fields")
    for tag in ("feature_tag","content_tag"):
        if tag in params and (not isinstance(params[tag],str) or len(params[tag])>64):raise ValueError("Invalid tag filter")
    if "is_third_platform" in params and (type(params["is_third_platform"]) is not int or params["is_third_platform"] not in (0,1)):raise ValueError("Invalid cross-platform filter")
    scope=params.get("advertise_switch")
    if type(scope) is not int or scope not in (0,1) or scope in scopes:raise ValueError("Need distinct scopes 0 and 1")
    if not isinstance(params.get("user_id"),str) or not params["user_id"].strip():raise ValueError("Record user_id")
    if params.get("order_type")!=1 or type(params.get("order_type")) is not int:raise ValueError("Use newest order, not scope-dependent reading rank")
    for key in ("page_number","page_size","note_type"):
        if type(params.get(key)) is not int:raise ValueError("Record explicit note/page settings")
    if not 1<=params["page_number"]<=1000 or not 1<=params["page_size"]<=8 or params["note_type"] not in (1,2,3,4):raise ValueError("Invalid note/page settings")
    other={key:value for key,value in params.items() if key!="advertise_switch"}
    if base is None:base=other
    if base!=other:raise ValueError("Only traffic scope may differ")
    stamp=entry["collected_at"];dt=datetime.datetime.fromisoformat(stamp.replace("Z","+00:00"))
    if dt.tzinfo is None:raise ValueError("Timezone required")
    path=pathlib.Path(entry["response_file"])
    if not path.is_absolute():path=manifest.parent/path
    raw=path.read_bytes();digest=hashlib.sha256(raw).hexdigest()
    r=json.loads(raw)
    if r.get("error") is not None or r.get("status")!="succeeded" or r.get("action")!=entry["action"]:raise ValueError("Failed or wrong response")
    rid=r.get("request_id")
    if not isinstance(rid,str) or not rid.strip() or rid in request_ids:raise ValueError("Distinct request IDs required")
    request_ids.add(rid)
    envelope=r.get("data")
    if not isinstance(envelope,dict) or envelope.get("success") is not True:raise ValueError("PGY business failure")
    data=envelope.get("data")
    if not isinstance(data,dict) or not isinstance(data.get("list"),list):raise ValueError("Expected non-null note list")
    notes={}
    for item in data["list"]:
        if not isinstance(item,dict):raise ValueError("Bad note object")
        note=item.get("noteId")
        if not isinstance(note,str) or not note.strip() or note in notes:raise ValueError("Distinct real noteId required per page")
        value=item.get("readNum")
        if type(value) is int and value>2**53-1:raise ValueError("Unsafe JSON count; preserve an original digit string instead")
        if isinstance(value,str) and value.isascii() and value.isdigit():value=int(value)
        if value is not None and (type(value) is not int or value<0):raise ValueError("readNum must be integer/digit string or missing")
        notes[note]=value
    scopes[scope]={"notes":notes,"request_id":rid,"collected_at":stamp,"source_file":str(path.resolve()),"sha256":digest}
rows=[]
for note in sorted(set(scopes[0]["notes"])|set(scopes[1]["notes"])):
    organic=scopes[0]["notes"].get(note);all_reads=scopes[1]["notes"].get(note)
    present0=note in scopes[0]["notes"];present1=note in scopes[1]["notes"]
    state="both" if present0 and present1 else ("organic_only" if present0 else "all_only")
    delta=all_reads-organic if organic is not None and all_reads is not None else None
    rows.append({"noteId":note,"coverage":state,"organic_reads":organic,"all_reads":all_reads,"observed_difference":delta,
                 "review":"missing_metric" if state=="both" and delta is None else ("negative_difference" if delta is not None and delta<0 else ""),
                 "organic_request_id":scopes[0]["request_id"],"all_request_id":scopes[1]["request_id"],
                 "organic_collected_at":scopes[0]["collected_at"],"all_collected_at":scopes[1]["collected_at"],
                 "organic_source_sha256":scopes[0]["sha256"],"all_source_sha256":scopes[1]["sha256"]})
def cell(value):
    if value is None:return ""
    if isinstance(value,int):return value
    return "'"+value if value.lstrip().startswith(("=","+","-","@")) or value.startswith(("\t","\r","\n")) else value
with target.open("x",encoding="utf-8-sig",newline="") as output:
    writer=csv.DictWriter(output,fieldnames=["noteId","coverage","organic_reads","all_reads","observed_difference","review","organic_request_id","all_request_id","organic_collected_at","all_collected_at","organic_source_sha256","all_source_sha256"])
    writer.writeheader();writer.writerows({key:cell(value) for key,value in row.items()} for row in rows)
print(str(target))
```

运行 `python3 compare_pgy_scopes.py scope-manifest.json scope-comparison.csv`，两份原文件和清单与 CSV 一起保留。observed_difference 只是两次观察相减，不是已证实的付费归因阅读。缺值留空；负差保留并标记核查，不截成零。解释结果之前，先检查时间、覆盖和指标定义。来源：测试数据是合成的，不能证明真实的两份计数永远只差推广流量。

博主趋势方面，xiaohongshu.pgy.get_blogger_core_data 的说明明确有 data.data.dailyData 与 data.data.sumData，但没有列出每日 CPM/日期的全部子键。不要把核心数据的汇总值塞进 compare_pgy_scopes.py，也不要用中位数或比率相减来编造推广阅读人数。

## 拿到表后，按什么顺序做筛选？

先看 coverage、review 和两次观察时间，再看阅读数。organic_only、all_only 表示这篇笔记只出现在其中一页，不是另一种口径为 0。missing_metric 表示要先检查保存的原响应；negative_difference 是核查提示，不是负数推广量。两页都成功但都为空，只说明本次选定的两页为空，不代表博主没有历史笔记。

初筛时，把匹配笔记的自然阅读作为一个内容表现信号，未匹配项另留待审，并在结论里保留笔记ID与观察时间。不要用不同笔记集合算出的比率给博主排名。这次比较每种口径只覆盖一页，不是账号全量审计；要扩展页数，另行确认调用成本，并沿用同一套筛选规则。

每行保存两份原响应的 SHA-256。把原始字节与 scope-manifest.json、CSV 一起留存。哈希把每行绑定到本地来源字节，但不证明服务器真实性，也不证明手填的采集时间。超大的裸 JSON 整数、无效计数、未知筛选字段和不一致的口径，都会在生成 CSV 之前停止导出；以数字字符串返回的计数保留完整精度。