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

# 小红书合作投完了，怎么回收这批笔记的数据并向客户复盘？

> 固定合作笔记名单与观察窗口，交付公开互动快照、缺失清单和两轮变化，先判断覆盖再解释表现。

给客户复盘一批已发布的小红书合作笔记时，先固定约定的笔记名单，在约定时间用 `data:xiaohongshu.app_v2.get_image_note_detail` 或 `data:xiaohongshu.app_v2.get_video_note_detail` 观察同一批笔记，再交一张能回到来源的变化表。变化表回答三件事：哪些内容还在积累互动、哪些需要补查、哪些数据还不能支持结论。临时搜来的热门笔记不能替代实际合作名单。

本流程回收公开点赞、收藏、评论、分享，保存每轮快照并比较两轮净变化。阅读和曝光有独立口径，最后的蒲公英小节只导出已有文档说明的蒲公英字段；成交、获客、归因涨粉和完整结案仍需对应的订单和后台证据。

## 先跟客户对齐：这轮要回答哪个问题？

只有几篇作品时，一次人工记录也能完成；需要多篇、多轮回收并保留来源时，再用本页的脚本。取数前先写清名单、观察窗口、所需指标和允许花费，避免取完一大包数据才发现客户要的是另一种报表。

| 客户想知道            | 这份交付怎么用                  | 还需要什么                 |
| ---------------- | ------------------------ | --------------------- |
| 合作作品现在各有多少互动     | 每篇一行，保留公开计数与实际采集时间       | 缺失项另列原因；没有值不写0。       |
| 上次回收到现在还有没有增加    | 对同一笔记比较两次观察，保留前值、后值、差值   | 两轮都须有该指标；负变化也保留。      |
| 哪位博主或哪种内容更值得继续研究 | 先检查名单覆盖与作品年龄，再结合内容和评论看差异 | 互动不能直接证明投放带来的销售或质量高低。 |
| 曝光、阅读、涨粉或销售带来了多少 | 另核对有权限后台的定义与归因窗口         | 公开互动表不能补出不存在的曝光或转化证据。 |

## 拿到变化表，先看缺口，再看增量

下表是**虚构读表示例**，只演示判断方法，不是采集结果：

| 表中看到什么              | 可以怎么写复盘              | 下一步                      |
| ------------------- | -------------------- | ------------------------ |
| 同一篇收藏100→150，两次时间明确 | 本观察区间净增50次收藏         | 回看内容与讨论，不能直接写“多带来50个买家”。 |
| 只在后续有一行             | 本轮取到数据，基线缺失，无法算区间净变化 | 查基线采集日志，不把前值补0。          |
| 两轮都没有这篇             | 合作名单中有这一篇，但两轮都缺数据    | 查漏采、失败或内容状态，不能直接说已删除。    |
| 评论数120→115          | 观察到计数减少5，保留事实        | 核对时间、来源与口径，不改成0或猜成负面舆情。  |

比较不同作品时，从每篇各自的发布时间起算，优先对齐发布后第 1 天和第 7 天。比如甲笔记是第 7 天，乙笔记已经发布 30 天，就把乙笔记的本轮数字放进长周期观察。复盘表里每项增量都附前后两次查询时间。

## 怎么安排一轮回收？

1. 固定合作名单：保存笔记 ID、图文/视频类型、合作批次与原始链接；不要为取得已有 ID 再做一次搜索。比较脚本的 `roster.json` 只放约定的 ID 字符串，作者和批次等信息另外留在合作工作表。
2. 约定观察轮次：例如发布后 1、7、30 天。计划时间和实际查询时间分开记录；本页不创建定时采集任务，导出时间也不是采集时间。
3. 按正确类型保存原响应：图文笔记用图文详情动作，视频笔记用视频详情动作。类型未知时先核对，不轮流试两个收费动作；每篇每轮单独保存文件。
4. 先核对名单覆盖：成功项进入本轮导出清单，失败或未采集项另记日志。导出脚本遇到失败输入会停止，不悄悄补零。需要重查时先确认预算，只补已批准的失败项。
5. 比较同一名单的两轮：先确认 baseline 确实是较早的一轮，再离线生成变化表。先解释缺口，再解释可以比较的数字，最后列出要问博主或客户的事项。

交给客户的是快照 CSV、两轮变化 CSV 和一份简短说明：本轮计划多少篇、实际覆盖多少篇、缺哪几篇及原因、哪些变化可比较、哪些结论还缺证据。原始响应和清单作为内部核对依据留存；工作表里的内容评价与后续建议由人工填写，脚本不给博主打分。

## 先估成本，已有数据先复用

每轮预算为“图文条数×图文详情当前单价＋视频条数×视频详情当前单价”，再按批准轮次合计；执行前分别免费 Inspect。另取蒲公英字段、评论或模型分析另算。失败和业务错误也可能计费，竞品“失败免费”的承诺不适用。

改表、重新比较已保存的文件不需要再次取数。只在确实需要新观察时才发起新请求；本页的 Python 脚本都在本地处理文件，不会自动购买数据或上传客户报表。

先按第 1–6 步完成公开互动回收；确需曝光或阅读时，再用最后的蒲公英小节。两部分的动作、字段和费用分开，不混用。

## 1. 根据笔记类型核对合同

图文笔记用 `data:xiaohongshu.app_v2.get_image_note_detail`，视频笔记用 `data:xiaohongshu.app_v2.get_video_note_detail`。只 Inspect 需要的动作，确认当前价格与业务错误说明。

```bash
curl -sS https://api.beatapi.io/v1/capabilities/inspect \
  -H 'Content-Type: application/json' \
  -d '{"reference":"data:xiaohongshu.app_v2.get_image_note_detail"}'
```

不要为试探笔记类型自动连续调用两个动作；类型未知时先核对笔记来源。错误 ID 或链接解析失败可能返回正常的业务错误响应，并且计费。

## 2. 获取一篇并保存原始文件

```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.app_v2.get_image_note_detail","params":{"note_id":"<note_id>"}}' \
  -o note-1.json
```

视频笔记改用视频详情动作，输入同样使用已确认的 ID。不同笔记或不同采集时间用不同文件名，不覆盖历史响应。记录每次请求的时间；导出时刻不是平台查询时刻。

## 3. 建立本地输入清单

创建自己的 targets.json，用实际 ID、响应文件名和当次查询时间替换示例中的占位值。targets.json 是本地导出清单，不是 BeatAPI 接口参数。

```json
[
  {"note_id":"<note_id>","file":"note-1.json","collected_at":"<actual_collection_time>"}
]
```

图文笔记在 data.data\[].note_list\[]，视频笔记在 data.data\[]。同一响应可能带有其他笔记，所以必须按目标 ID 匹配，不能直接取第一条记录。

## 4. 离线导出 CSV

在清单和响应所在的目录运行下面的导出脚本。遇到失败、未知动作或找不到目标时，脚本停止运行，不生成一行全零的假成功。缺失指标写空，真实的 0 保留；所有记录校验完后才替换 CSV。

```python
import csv
import json
from datetime import datetime
from decimal import Decimal, InvalidOperation
from pathlib import Path

def count(value):
    if value is None:
        return None
    try:
        if isinstance(value, bool):
            raise ValueError()
        number = Decimal(str(value))
        if not number.is_finite() or number < 0 or number != number.to_integral_value():
            raise ValueError()
        return int(number)
    except (ValueError, InvalidOperation):
        raise SystemExit("Expected a nonnegative integer count")

targets = json.loads(Path("targets.json").read_text(encoding="utf-8"))
rows = []
seen = set()
if not isinstance(targets, list):
    raise SystemExit("Expected a target list")
for target in targets:
    key = target.get("note_id")
    if not isinstance(key, str) or not key or key in seen:
        raise SystemExit("Missing or duplicate target ID")
    seen.add(key)
    try:
        stamp = datetime.fromisoformat(target["collected_at"].replace("Z", "+00:00"))
        if stamp.utcoffset() is None:
            raise ValueError()
    except (KeyError, ValueError, TypeError, AttributeError):
        raise SystemExit("Collection time must include date, time and timezone")
    payload = json.loads(Path(target["file"]).read_text(encoding="utf-8"))
    if payload.get("status") != "succeeded":
        raise SystemExit(f"Failed query: {target['file']}")
    upstream = payload.get("data", {})
    if upstream.get("success") is False or ("code" in upstream and upstream["code"] != 0):
        raise SystemExit(f"Upstream business error: {target['file']}")
    if not payload.get("request_id"):
        raise SystemExit("Missing request ID")
    action = payload["action"]
    if action == "xiaohongshu.app_v2.get_image_note_detail":
        notes = [note for wrapper in payload["data"]["data"] for note in wrapper.get("note_list", [])]
    elif action == "xiaohongshu.app_v2.get_video_note_detail":
        notes = payload["data"]["data"]
    else:
        raise SystemExit(f"Unexpected action: {action}")
    matches = [note for note in notes if note.get("id") == target["note_id"]]
    if len(matches) != 1:
        raise SystemExit(f"Target must match exactly once: {target['note_id']}")
    note = matches[0]
    rows.append({
        "note_id": target["note_id"],
        "title": note.get("title"),
        "likes": count(note.get("liked_count")),
        "saves": count(note.get("collected_count")),
        "comments": count(note.get("comments_count")),
        "shares": count(note.get("shared_count")),
        "views": count(note.get("view_count")),
        "collected_at": target["collected_at"],
        "request_id": payload["request_id"],
        "source_file": target["file"],
    })
if not rows:
    raise SystemExit("No targets; keep the previous CSV unchanged.")
def safe_cell(value):
    if isinstance(value, str) and value.lstrip().startswith(("=", "+", "-", "@")):
        return "'" + value
    return value
temporary = Path("note-metrics.csv.tmp")
with temporary.open("w", encoding="utf-8-sig", newline="") as output:
    writer = csv.DictWriter(output, fieldnames=list(rows[0]))
    writer.writeheader()
    writer.writerows({key: safe_cell(value) for key, value in row.items()} for row in rows)
temporary.replace("note-metrics.csv")
```

## 5. 比较快照，而不是伪造归因

保留每轮的 CSV 与原始 JSON，用 note_id 对齐同一篇笔记。总量相减只是两次观察之间的净变化，不能证明变化由投放带来，也不保证期间没有计数修订。没有 view_count 不补零，没有曝光字段就不算曝光成本。

在表格软件里导入 note_id 时选文本类型，避免长标识被改写。代码处理了公式前缀、换行和引号，但没有统一各动作的全部可选字段，也没有归一化指标的时间口径。

### 把投后回收做成可复核的变化表

手上是一批合作笔记时，不要每轮重新搜索来替换原名单。先固定笔记 ID、类型和约定回收时间；按同一名单回收首次与后续快照，保留每次的原始文件。某篇请求失败只补查那一篇，不重跑已成功的名单。笔记删除、不可见或本轮遗漏，都记为缺失，不按互动归零处理。

把两轮导出的文件分别复制为 `baseline.csv`、`followup.csv`，在同一目录运行下面的代码。交付文件 `note-metric-changes.csv` 每篇一行，包含两次采集时间、来源文件、各指标的前值/后值/净变化。两轮都出现才标为 `matched`；只出现一次标为 `new_only` 或 `baseline_only`，不会被悄悄丢弃。任何一侧缺少某个指标，就不计算该指标的差值。负差值照实保留，表示计数下调，不是代码错误。

比较前另建 `roster.json`，内容为约定的笔记 ID 字符串数组，例如 `["<note_id_1>","<note_id_2>"]`。`roster.json` 独立于两轮成功结果，不能从 CSV 反推，否则两轮都漏采的笔记会消失。输出 `missing_both` 表示两轮都没有该笔记；CSV 出现名单外的 ID 时，脚本停止检查。

本流程完成的是**已保存响应的固定名单复核**，不是自动批量采集。第一段导出脚本仍对失败响应立即停止，避免把错误计为有效记录。先把失败请求单独记录在 failures.json 里（笔记 ID、轮次、请求时间、错误、原始文件）；只把已验证成功的响应放进该轮的 targets.json，再导出成功快照。结果缺失本身分辨不出删除、请求失败还是漏采，必须对照 failures.json。整轮没有成功结果时，先处理失败再比较，不要用旧 CSV 冒充新一轮。

```python
import csv
import json
from decimal import Decimal, InvalidOperation
from pathlib import Path

metrics = ("likes", "saves", "comments", "shares", "views")
def load_snapshot(filename):
    with Path(filename).open(encoding="utf-8-sig", newline="") as source:
        rows = list(csv.DictReader(source))
    result = {}
    for row in rows:
        key = row["note_id"]
        if not key or key in result:
            raise SystemExit(f"Missing or duplicate note ID in {filename}")
        if not row["collected_at"]:
            raise SystemExit(f"Missing collection time in {filename}")
        result[key] = row
    if not result:
        raise SystemExit(f"Empty snapshot: {filename}")
    return result

roster = json.loads(Path("roster.json").read_text(encoding="utf-8"))
if not isinstance(roster, list) or not roster or any(not isinstance(v, str) or not v for v in roster):
    raise SystemExit("Expected a nonempty roster of note ID strings")
if len(roster) != len(set(roster)):
    raise SystemExit("Duplicate ID in roster")
before = load_snapshot("baseline.csv")
after = load_snapshot("followup.csv")
if (before.keys() | after.keys()) - set(roster):
    raise SystemExit("Snapshot contains IDs outside the agreed roster")
rows = []
for note_id in roster:
    old, new = before.get(note_id), after.get(note_id)
    row = {
        "note_id": note_id,
        "coverage": "matched" if old and new else ("new_only" if new else ("baseline_only" if old else "missing_both")),
        "before_collected_at": old["collected_at"] if old else "",
        "after_collected_at": new["collected_at"] if new else "",
        "before_source_file": old["source_file"] if old else "",
        "after_source_file": new["source_file"] if new else "",
    }
    for metric in metrics:
        a, b = old.get(metric, "") if old else "", new.get(metric, "") if new else ""
        row[metric + "_before"], row[metric + "_after"] = a, b
        numbers = []
        for value in (a, b):
            if value == "":
                numbers.append(None)
                continue
            try:
                number = Decimal(value)
                if not number.is_finite() or number < 0 or number != number.to_integral_value():
                    raise InvalidOperation
                numbers.append(number)
            except InvalidOperation:
                raise SystemExit(f"Non-numeric {metric} for {note_id}")
        delta = numbers[1] - numbers[0] if all(v is not None for v in numbers) else ""
        row[metric + "_delta"] = delta
    rows.append(row)

def safe_cell(value):
    if isinstance(value, str) and value.lstrip().startswith(("=", "+", "-", "@")):
        return "'" + value
    return value
temporary = Path("note-metric-changes.csv.tmp")
with temporary.open("w", encoding="utf-8-sig", newline="") as output:
    writer = csv.DictWriter(output, fieldnames=list(rows[0]))
    writer.writeheader()
    writer.writerows({key: safe_cell(value) for key, value in row.items()} for row in rows)
temporary.replace("note-metric-changes.csv")
```

验收时先筛出非 `matched` 行检查漏采，再按 likes_delta、saves_delta、comments_delta 看这批笔记公开互动的变化。不同笔记的采集时间不完全一致，差值表不能包装成平台统一时间窗的归因报告。脚本按文件角色比较，不自动推断先后；开始前确认 baseline 是较早的一次。

### 可交给 AI 的明确任务

> 按我提供的固定笔记名单与类型，核对相应详情接口，保存本轮原始响应和真实查询时间；将首次与本轮快照按笔记 ID 对齐，导出前值、后值、净变化及缺失名单。不要重新搜索替换样本，不把缺失指标填零，不补造曝光或归因数据。先报告预计调用次数与当前价格，取得本次采集授权后再执行；已保存文件的对比只在本地运行。

## 6. 费用与验收

N 篇笔记各查一次是 N 次详情调用；用已有原始文件导出 CSV 不增加平台调用。每次刷新都是新查询，金额以当前 Inspect 为准，各动作的错误计费边界分别核对。

依据：离线图文/视频样例，检查了两种路径、精确 ID 匹配、空值和零、公式前缀、失败时不覆盖旧 CSV；没有付费采集或实际投放效果测试。完整报告中未验证的字段见[结案报告边界](/zh/faq/xiaohongshu-report-availability)。

## 把已明确的蒲公英曝光、阅读字段做成结案表

结案名单需要曝光与阅读时，已核对的蒲公英详情说明列出了具体字段。BeatAPI 渲染器保留两层信封，路径为 `data.data.noteId` 以及同层的 impNum（曝光）、readNum（阅读）、likeNum、favNum、cmtNum。不要套用竞品的归一化字段；归因涨粉、分享、品牌和组件点击字段还没有被蒲公英说明证实。依据：官方说明、网关渲染器和合成样本测试，没有新增收费蒲公英实测。

先冻结一轮的笔记名单。2026-11-16 免费 Inspect 核价为每次 \$0.06；30 篇就是 30 次，按该价格为 \$1.80，不含发现与重查，执行前重新核价。只查名单内的笔记，失败也留档，不因 null 自动重买。请求体如下，其中的 ID 仅为示意，不能直接执行：

```json
{"action":"xiaohongshu.pgy.get_note_detail","params":{"note_id":"0123456789abcdef01234567"}}
```

每份实际完整响应对应一条清单记录，时间填真实采集时间，每轮使用新目录。转换脚本不联网：

```json
[{"note_id":"0123456789abcdef01234567","action":"xiaohongshu.pgy.get_note_detail","params":{"note_id":"0123456789abcdef01234567"},"http_status":200,"collected_at":"2026-11-16T10:00:00Z","response_file":"pgy-note.json"}]
```

把下面的脚本保存为 `pgy_report.py`。`pgy_report.py` 要求已核实的 24 位笔记 ID，核对返回的笔记身份和显式的内部业务成功，失败的名单行不丢弃。计数接受非负整数和纯数字字符串，缺值留空；无法解释的格式化数值会报错供核查，不擅自转换。

```python
import csv,datetime,hashlib,json,pathlib,re,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 not entries:raise ValueError("Nonempty roster manifest required")
fields={"impressions":"impNum","reads":"readNum","likes":"likeNum","saves":"favNum","comments":"cmtNum"}
rows=[];seen=set();request_ids=set()
def count(value):
    if value is None:return ""
    if type(value) is int and value>=0:return value
    if isinstance(value,str) and re.fullmatch(r"[0-9]+",value):return int(value)
    raise ValueError("Count must be a nonnegative integer or digit string")
def cell(value):
    text=str(value)
    return "'"+text if text.lstrip().startswith(("=","+","-","@")) or text.startswith(("\t","\r","\n")) else text
for entry in entries:
    note=entry["note_id"]
    if not isinstance(note,str) or not re.fullmatch(r"[0-9a-fA-F]{24}",note) or note in seen:
        raise ValueError("Use distinct verified 24-character note IDs in this round")
    seen.add(note)
    if entry.get("action")!="xiaohongshu.pgy.get_note_detail" or entry.get("params")!={"note_id":note}:
        raise ValueError("Manifest must bind the actual action and note_id params")
    http_status=entry.get("http_status")
    if type(http_status) is not int or not 100<=http_status<=599:raise ValueError("Record actual HTTP status")
    stamp=entry["collected_at"]
    if datetime.datetime.fromisoformat(stamp.replace("Z","+00:00")).tzinfo is None:raise ValueError("Timestamp needs timezone")
    path=pathlib.Path(entry["response_file"])
    if not path.is_absolute():path=manifest.parent/path
    raw=path.read_bytes();response=json.loads(raw)
    error=response.get("error")
    if error is not None:
        if not isinstance(error,dict) or http_status<400:raise ValueError("Invalid HTTP error envelope")
        if not isinstance(error.get("code"),str) or not error["code"].strip():raise ValueError("Missing error code")
        request_id=error.get("request_id")
    else:
        if http_status!=200 or response.get("action")!="xiaohongshu.pgy.get_note_detail":raise ValueError("Unexpected response action or HTTP status")
        request_id=response.get("request_id")
    if not isinstance(request_id,str) or not request_id.strip() or request_id in request_ids:raise ValueError("Distinct request IDs required")
    request_ids.add(request_id)
    row={"note_id":note,"collected_at":stamp,"request_id":request_id,"source_file":str(path),
         "source_sha256":hashlib.sha256(raw).hexdigest(),"state":"gateway_failed","http_status":http_status,"error_code":error["code"] if error is not None else "",
         **{key:"" for key in fields},"read_to_impression_ratio":"","ratio_state":"unavailable"}
    if error is None and response.get("status")=="succeeded":
        envelope=response.get("data")
        if not isinstance(envelope,dict):raise ValueError("Missing PGY envelope")
        if envelope.get("success") is False:row["state"]="pgy_business_failed"
        elif envelope.get("success") is not True:raise ValueError("PGY success must be explicit boolean")
        elif envelope.get("data") is None:row["state"]="no_payload"
        else:
            data=envelope["data"]
            if not isinstance(data,dict) or data.get("noteId")!=note:raise ValueError("Response note identity mismatch")
            for label,key in fields.items():row[label]=count(data.get(key))
            row["state"]="available" if all(row[key]!="" for key in fields) else "partial_metrics"
            imp,reads=row["impressions"],row["reads"]
            if imp=="" or reads=="":row["ratio_state"]="missing_input"
            elif imp==0:row["ratio_state"]="zero_denominator"
            else:
                row["read_to_impression_ratio"]=reads/imp
                row["ratio_state"]="review_gt_one" if reads>imp else "computed"
    elif error is None:raise ValueError("Unexpected gateway status")
    rows.append(row)
summary={"roster_notes":len(rows),"state_counts":{},"scope":"One saved observation round; no attributed follows or component clicks"}
for row in rows:summary["state_counts"][row["state"]]=summary["state_counts"].get(row["state"],0)+1
target.mkdir()
with (target/"pgy-note-report.csv").open("x",encoding="utf-8-sig",newline="") as output:
    writer=csv.DictWriter(output,fieldnames=list(rows[0]));writer.writeheader()
    writer.writerows({key:cell(value) for key,value in row.items()} for row in rows)
(target/"coverage.json").write_text(json.dumps(summary,ensure_ascii=False,indent=2),encoding="utf-8")
print(str(target/"pgy-note-report.csv"))
```

运行 `python3 pgy_report.py pgy-manifest.json pgy-round-1`。先看 coverage.json 再排序 CSV：网关失败、内部业务失败、空数据、部分指标、可用指标分别计数；原始响应保留错误细节和字段的原始表示，与清单一起保存。

read_to_impression_ratio 是脚本计算的阅读/曝光，不是平台直接给出的转化率或去重读者指标。缺输入时留空；曝光为零时留空并记 zero_denominator；阅读超过曝光时保留计算结果并标 review_gt_one，不强行压到 100%。对比前核对采集时间与指标口径。蒲公英字段表不冒充完整归因报表。目标目录必须不存在；写入中断时先检查半成品，再换新目录名。

清单记录实际 HTTP 状态和 action/params。HTTP 失败从 error.code 与 error.request_id 读取，不构造假的顶层 failed 响应；curl 非零退出时也要保留响应正文。没有 JSON 响应的网络失败另写采集日志，转换脚本不能替这类失败编造 HTTP 结果。

获准采集真实笔记时，把实际请求体保存为 pgy-request.json，再用新的文件名执行一次下面的命令。把 pgy-http-status.txt 里的真实状态抄进该笔记的清单记录，不覆盖已有轮次。这一步是另行授权的收费采集，不属于本地转换。

```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' \
  --data-binary @pgy-request.json \
  -o pgy-note.json -w '%{http_code}\n' > pgy-http-status.txt
```