跳到导航

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

给客户复盘一批已发布的小红书合作笔记时,先固定约定的笔记名单,在约定时间用 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 需要的动作,确认当前价格与业务错误说明。

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. 获取一篇并保存原始文件

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 接口参数。

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

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

4. 离线导出 CSV

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

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 冒充新一轮。

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;没有付费采集或实际投放效果测试。完整报告中未验证的字段见结案报告边界。

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

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

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

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

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

[{"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,核对返回的笔记身份和显式的内部业务成功,失败的名单行不丢弃。计数接受非负整数和纯数字字符串,缺值留空;无法解释的格式化数值会报错供核查,不擅自转换。

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 里的真实状态抄进该笔记的清单记录,不覆盖已有轮次。这一步是另行授权的收费采集,不属于本地转换。

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