> 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_notes（note_type: 3）查询候选博主的合作案例，用 pgy_cases.py 核对单页 brandName 标签，再通过 brand_roster.py 合并跨博主品牌证据并隔离冲突记录。

要查候选名单里谁给竞品做过推广，用 `xiaohongshu.pgy.get_blogger_notes` 逐个查博主的合作案例，传入博主的 `user_id` 并设置 `note_type:3`。核对案例里返回的品牌名称，再列出匹配的博主、笔记和出处。邀约前打开入选笔记，判断做过的内容是否接近你的产品，并把档期和排他约定写进待确认清单。

只有一个竞品品牌名时，先用公开搜索找候选博主，再逐个核对合作案例。交付时注明查了哪些博主和哪些案例页。

## 最后拿到什么，怎么用来安排邀约？

最后得到两张表：一张列出样本中命中目标品牌的博主，一张列出对应笔记，供你回到博主主页核对原内容。表里给的是笔记 ID，不会自动生成可打开的分享链接。品牌未知和相互矛盾的记录单独保留，不挤进已确认名单。

下表用占位示例说明不同结果的解读方式（并非真实博主记录）：

| 候选人  | 这轮查到了什么         | 联系前怎么处理                               |
| ---- | --------------- | ------------------------------------- |
| 博主 A | 两篇案例标有目标品牌      | 先看产品类型与表达方式是否适合这次需求；有意向时再问档期、排他约定和报价。 |
| 博主 B | 案例有返回，但品牌为空     | 记为“待核实”，不能写“没有接过竞品”。                  |
| 博主 C | 同一笔记在两份记录中品牌不一致 | 先核对笔记与来源，不把这篇笔记计入竞品合作次数。              |

“合作过竞品”既可能意味着相关经验，也可能意味着需要确认排他条件，不是自动淘汰或优先合作的评分。表里没有合同金额、实际投放成本或转化效果；不要把当前报价当成上一单真实付款。

## 只有竞品品牌名，还没有候选博主怎么办？

先按[笔记搜索指南](/zh/guides/xiaohongshu-notes-research)用品牌名和已确认的别名搜索相关笔记，结合实际产品和内容筛掉同名干扰，把相关作者列为待核候选。搜索只能说明这些作者提到过品牌；要补充合作证据，再用本页流程核查每位作者的博主案例。

“先找相关作者，再查博主案例”这条路线适合建立研究起点。如果任务是统计搜索样本里报备商单的比例，或逐篇确认某篇笔记报备的品牌，目前还缺搜索合作标记和单篇报备品牌的固定返回，需要另外补核资料，不能用品牌关键词的命中率代替。

## 1. 先把这轮要查的人和品牌范围定下来

从已有候选库取博主的稳定 ID，不用昵称拼 ID。如果还没有名单，先走[按内容和预算建立候选库](/zh/guides/xiaohongshu-creator-shortlist)，再回到这里核查选中的人。

保留原候选表里的所有人，手动增加“本轮状态、代表案例、内容适配、待问事项、是否联系”五列。这五列是你的邀约底稿，不是脚本生成的评分；后面的命中名单只用来补充原候选表，不能替换它。空页、未命中和查询失败的人也留在原表，分别标注“本轮未见匹配”或“待核实”。

为这轮写清三件事：要核查哪些博主、哪个竞品品牌、最多愿意看多少页。品牌的中文名、英文名和子品牌可能分别出现；只把你人工确认属于同一目标的返回标签合在一起，不能靠相似名字自动认定。

第一轮每人看一页，再给确实值得继续了解的人补页。示例请求按阅读排序，先看阅读较高的合作案例；如果目标是近期合作，改按最新排序，并在整轮保持一致。无论哪种排序，第一页都不是博主的全部历史。

## 2. 看合作案例，不先把所有资料都买一遍

用合作案例筛选，一次取一位已知博主的一页。先不要给每个人追加粉丝画像、详细报价或每篇结案数据：决定进一步接洽某位博主之后，再按具体问题补这些资料。

当前案例查询单价见[价格页](https://beatapi.io/zh/pricing)。20位候选、每人一页就是20次案例页查询；按需要再增加找人、详情、追加页或模型分析。已有案例原件直接复用，先看首批能否回答这轮邀约问题。

下方技术步骤提供完整请求和两个本地脚本。每次实际查询都保存响应和请求记录：博主 ID、筛选条件、页码和采集时间。请求记录里的博主 ID 只说明这次查询的是谁，平台并没有另外证明作者归属，所以复核时仍要打开对应笔记看作者。

## 3. 把品牌线索整理出来，再看具体内容

先对每一页运行 `pgy_cases.py`，查看案例中的品牌名；再把确认属于目标品牌的精确标签填入品牌清单，用 `brand_roster.py` 合并多位博主、多页的记录。同一笔记重复出现只计一次，两个品牌名冲突时，脚本不会替你选一个。

拿到结果后按这个顺序看：

1. **先看有多少真正命中。** `coverage.json` 分开列出命中、品牌未知、品牌冲突和其他品牌。零命中只表示这轮样本没有匹配，不能扩大成“品牌没投过”或“博主从没合作”。
2. **再核对具体笔记。** 在 `brand-evidence.csv` 找到笔记 ID，再从单页 `cases.csv` 取标题和日期；到对应博主主页找到该内容，核对笔记 ID、作者和品牌。无法定位就填“待核实”，不自行拼一个缺访问令牌的链接，也不为找内容自动加买详情。品牌名是来源里的标签，不是合同或付款凭证。
3. **最后整理要联系的人。** `creator-roster.csv` 只列出命中的博主和对应笔记，不含空页或失败的候选。回到已有候选库，按同一个博主 ID 补上昵称和你的选人理由，再人工安排邀约顺序。不要按昵称连接不同账号。

原始数据和两张表的 JSON 版本都会保留，出现争议时可以回看。表格软件导入时把 ID 设为文本，避免长编号被改写。每条记录都要人工复核；脚本不联系博主，也不作合作承诺。

## 4. 联系之前，还要问清什么？

核对一两篇代表内容是否真的接近本次产品，而不只看“合作次数”。内容合适后，再确认档期、是否接受这类产品、是否有竞品排他、交付形式及当前报价。如果要比较案例效果，去[读取已确认笔记的曝光和阅读](/zh/guides/xiaohongshu-note-metrics)，不要用品牌标签推算效果。

查不到品牌、数据冲突或某页报错时，在原候选表的“本轮状态”里填“待核实”，并写明卡在哪一步。失败页会让脚本停止，所以有没有输出行不能用来判断这个人是否值得合作；没有记录也不是负面结论。新增查询要针对具体待解的问题，不要对所有人把所有接口轮一遍。

## 技术步骤：采集一页合作案例

`data:xiaohongshu.pgy.get_blogger_notes` 用 `note_type: 3` 选择合作笔记。下面的示例用 `order_type: 2` 按阅读排序，用 `advertise_switch: 1` 保留全部流量口径。把 user_id 换成候选库里已核实的 ID，每位博主使用不同的文件名。

```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_notes","params":{"user_id":"<user_id>","note_type":3,"order_type":2,"advertise_switch":1,"page_number":1,"page_size":8}}' \
  -o creator-sponsored-notes.json
```

下面每个参数回答不同的问题，不要混用：

| 你要调整什么     | 参数与含义                                              |
| ---------- | -------------------------------------------------- |
| 最新、阅读、互动顺序 | `order_type` 分别为 1、2、3                             |
| 全部流量或自然流量  | `advertise_switch` 为 1 或 0；与是不是合作笔记不是一回事           |
| 只看跨域合作     | `is_third_platform: 1`；默认 0 不加这项限制                 |
| 翻下一页       | `page_number`，不是找博主用的 page_num；范围 1–1000，不代表实际有这些页 |
| 每页数量       | `page_size` 为 1–8；示例 8                             |

note_type 的 1/2/4 分别是图文/视频/全部，与 3 是单选关系，一个字段不能同时表示“仅合作视频”。content_tag、feature_tag 的取值参考实际博主详情里的标签，不要把示例当完整字典。翻页时条件和排序不变，遇到空页、重复整页、错误或预算上限就停止；不要自动切到输出结构不同的 V2 动作。

为每份实际响应保存一个 `case-request.json`。下面是格式示例，时间、ID 和页码要换成真实调用的值：

```json
{"action":"xiaohongshu.pgy.get_blogger_notes","params":{"user_id":"YOUR_VERIFIED_USER_ID","note_type":3,"order_type":2,"advertise_switch":1,"page_number":1,"page_size":8},"collected_at":"2026-11-16T10:00:00Z"}
```

## 技术步骤：先整理单页，再合并品牌名单

把下面的脚本保存为 `pgy_cases.py`。输入是完整的 BeatAPI 响应，不是截断预览。响应中的合作案例列表位于 `data.data.list[]`，笔记键为 `noteId`；`pgy_cases.py` 在本地按该结构校验已保存响应。

```python
import csv,datetime,hashlib,json,pathlib,sys
source,manifest,target=map(pathlib.Path,sys.argv[1:4])
request=json.loads(manifest.read_text(encoding="utf-8"));params=request["params"]
if request.get("action")!="xiaohongshu.pgy.get_blogger_notes" or params.get("note_type")!=3 or type(params.get("note_type")) is not int:
    raise ValueError("Record the actual sponsored-note request")
user=params.get("user_id")
if not isinstance(user,str) or not user.strip():raise ValueError("Actual creator user_id required")
for key,lo,hi in (("page_number",1,1000),("page_size",1,8)):
    if type(params.get(key)) is not int or not lo<=params[key]<=hi:raise ValueError("Record actual page and page size")
if params.get("advertise_switch") not in (0,1) or type(params.get("advertise_switch")) is not int:raise ValueError("Record traffic scope explicitly")
stamp=request["collected_at"]
if datetime.datetime.fromisoformat(stamp.replace("Z","+00:00")).tzinfo is None:raise ValueError("Timezone required")
raw=source.read_bytes();r=json.loads(raw)
if r.get("error") is not None:raise ValueError("Saved HTTP error; diagnose before export, do not retry automatically")
if r.get("status")!="succeeded" or r.get("action")!=request["action"]:raise ValueError("Expected successful note cases")
request_id=r.get("request_id")
if not isinstance(request_id,str) or not request_id.strip():raise ValueError("Missing request_id")
envelope=r.get("data")
if not isinstance(envelope,dict) or envelope.get("success") is not True:raise ValueError("PGY business result not successful")
data=envelope.get("data")
if not isinstance(data,dict) or not isinstance(data.get("list"),list):raise ValueError("No case list; null is not an empty list")
keys=["title","date","isVideo","isAdvertise","brandName","readNum","likeNum","collectNum","thirdReadUserNum"]
rows=[];seen={};brands={};duplicates=0;missing_brand=0
for item in data["list"]:
    if not isinstance(item,dict):raise ValueError("Invalid case object")
    note=item.get("noteId")
    if not isinstance(note,str) or not note.strip() or "<" in note or ">" in note:raise ValueError("Missing real noteId")
    evidence=json.dumps({key:{"present":key in item,"value":item.get(key)} for key in keys},ensure_ascii=False,sort_keys=True)
    if note in seen:
        if seen[note]!=evidence:raise ValueError("Conflicting duplicate case; review original observations before brand grouping")
        duplicates+=1;continue
    seen[note]=evidence
    brand=item.get("brandName")
    if brand is not None and not isinstance(brand,str):raise ValueError("Unexpected brandName representation")
    if brand is None or not brand.strip():missing_brand+=1
    else:brands.setdefault(brand,[]).append(note)
    rows.append({"creator_user_id":user,"noteId":note,**{key:item.get(key) for key in keys},
                 "isVideo_type":type(item["isVideo"]).__name__ if "isVideo" in item else "missing",
                 "isAdvertise_type":type(item["isAdvertise"]).__name__ if "isAdvertise" in item else "missing",
                 "advertise_switch":params["advertise_switch"],"page_number":params["page_number"],
                 "request_id":request_id,"collected_at":stamp,"manual_review":""})
def cell(value):
    if value is None:return ""
    text=value if isinstance(value,str) else json.dumps(value,ensure_ascii=False,separators=(",",":"))
    return "'"+text if text.lstrip().startswith(("=","+","-","@")) or text.startswith(("\t","\r","\n")) else text
report={"request":request,"request_id":request_id,"source_sha256":hashlib.sha256(raw).hexdigest(),
        "returned_occurrences":len(data["list"]),"unique_notes":len(rows),"duplicate_occurrences":duplicates,
        "missing_brand_notes":missing_brand,"brand_labels":brands,"reported_total":data.get("total"),
        "scope":"One saved page; raw brand labels, not full cooperation history or deduplicated brand entities",
        "creator_binding":"Request manifest only; output list does not establish creator identity independently"}
target.mkdir()
with (target/"cases.csv").open("x",encoding="utf-8-sig",newline="") as output:
    writer=csv.DictWriter(output,fieldnames=["creator_user_id","noteId",*keys,"isVideo_type","isAdvertise_type","advertise_switch","page_number","request_id","collected_at","manual_review"])
    writer.writeheader();writer.writerows({key:cell(value) for key,value in row.items()} for row in rows)
(target/"raw-response.json").write_bytes(raw)
(target/"review.json").write_text(json.dumps(report,ensure_ascii=False,indent=2),encoding="utf-8")
print(str(target/"cases.csv"))
```

```bash
python3 pgy_cases.py creator-sponsored-notes.json case-request.json case-review-1
```

先看单页 `cases.csv` 与 `review.json`，确认实际品牌标签。readNum 是阅读，thirdReadUserNum 的说明是站外阅读人数，不能改叫保证进店人数。isAdvertise/isVideo 按原值和类型保留，不把任意字符串当布尔；矛盾标记必须人工查看。单页相同 ID 的证据冲突会在输出前停止。total 是该案例筛选下的匹配数，与找博主列表的分页上限不是同一口径。

再建立 `brand-input.json`：填写人工确认的精确品牌标签，并列出每份响应/请求记录。把下面的占位品牌名替换为人工确认的精确标签，文件路径相对于 `brand-input.json`：

```json
{"brand_labels":["Example Brand","Example Brand Official"],"pages":[{"response":"creator-sponsored-notes.json","manifest":"case-request.json"},{"response":"creator-two-notes.json","manifest":"creator-two-request.json"}]}
```

保存下面的 `brand_roster.py`，与单页脚本放在一起：

```python
import csv,hashlib,json,os,pathlib,subprocess,sys,tempfile
parser,config_path,target=map(pathlib.Path,sys.argv[1:4])
config=json.loads(config_path.read_text(encoding='utf-8'))
labels=config.get('brand_labels');sources=config.get('pages')
if not isinstance(labels,list) or not labels or any(not isinstance(x,str) or not x.strip() for x in labels) or len(set(labels))!=len(labels):
    raise ValueError('Provide unique exact brand labels, manually reviewed as one brand')
if not isinstance(sources,list) or not sources:raise ValueError('Provide saved response/manifest pairs')
if target.exists():raise ValueError('Never overwrite an existing report')
os.umask(0o077)
observations=[];provenance=[];saved=[];seen_sources=set();ownership={};conditions=None
with tempfile.TemporaryDirectory() as temporary:
    temp=pathlib.Path(temporary)
    for index,entry in enumerate(sources):
        if not isinstance(entry,dict) or set(entry)!={'response','manifest'}:raise ValueError('Each page needs response and manifest')
        response=(config_path.parent/entry['response']).resolve();manifest=(config_path.parent/entry['manifest']).resolve()
        raw=response.read_bytes();manifest_raw=manifest.read_bytes()
        fingerprint=(hashlib.sha256(raw).hexdigest(),hashlib.sha256(manifest_raw).hexdigest())
        if fingerprint in seen_sources:raise ValueError('Duplicate source/manifest pair')
        seen_sources.add(fingerprint);saved.append((raw,manifest_raw))
        output=temp/str(index)
        frozen_response=temp/(str(index)+'-response.json');frozen_manifest=temp/(str(index)+'-manifest.json')
        frozen_response.write_bytes(raw);frozen_manifest.write_bytes(manifest_raw)
        result=subprocess.run([sys.executable,str(parser),str(frozen_response),str(frozen_manifest),str(output)],capture_output=True,text=True)
        if result.returncode:raise ValueError('Page '+str(index+1)+' failed the single-page validator; inspect it locally')
        review=json.loads((output/'review.json').read_text(encoding='utf-8'));request=review['request'];params=request['params']
        scope={k:v for k,v in params.items() if k not in ('user_id','page_number','page_size')}
        if conditions is None:conditions=scope
        elif scope!=conditions:raise ValueError('Mixed filters/order/traffic scope; report separately')
        user=params['user_id'];stamp=request['collected_at']
        provenance.append({'source_number':index+1,'response_sha256':fingerprint[0],'manifest_sha256':fingerprint[1],
                           'request':request,'request_id':review['request_id'],'missing_brand_notes':review['missing_brand_notes'],
                           'unique_notes':review['unique_notes'],'reported_total':review['reported_total']})
        for item in json.loads(raw)['data']['data']['list']:
            note=item['noteId']
            if note in ownership and ownership[note]!=user:raise ValueError('Same note attributed to multiple creator manifests; resolve before reporting')
            ownership[note]=user
            observations.append({'creator_user_id':user,'note_id':note,'brand_label':item.get('brandName'),
                                 'source_number':index+1,'collected_at':stamp,'request_id':review['request_id']})
by_note={}
for row in observations:by_note.setdefault((row['creator_user_id'],row['note_id']),[]).append(row)
evidence=[];roster={};unknown=0;conflicts=0;nonmatch=0
for (creator,note),rows in sorted(by_note.items()):
    distinct={row['brand_label'] for row in rows}
    if len(distinct)>1:state='conflicting_brand_observations';conflicts+=1
    elif next(iter(distinct)) is None or not next(iter(distinct)).strip():state='unknown_brand';unknown+=1
    elif next(iter(distinct)) in labels:state='matched_exact_label';roster.setdefault(creator,[]).append(note)
    else:state='other_brand_label';nonmatch+=1
    evidence.append({'creator_user_id':creator,'note_id':note,'classification':state,'observed_labels':sorted(distinct,key=lambda x:(x is not None,str(x))),
                     'source_numbers':sorted({row['source_number'] for row in rows}),'collected_at':sorted({row['collected_at'] for row in rows}),
                     'manual_review_required':True})
def cell(value):
    text=value if isinstance(value,str) else json.dumps(value,ensure_ascii=False)
    return "'"+text if text.lstrip().startswith(('=','+','-','@')) or text.startswith(('\t','\r','\n')) else text
summary={'exact_labels_selected':labels,'conditions':conditions,'source_pages':len(sources),'unique_creator_note_pairs':len(evidence),
         'matched_notes':sum(map(len,roster.values())),'matched_creators':len(roster),'unknown_brand_notes':unknown,
         'conflicting_brand_notes':conflicts,'other_brand_notes':nonmatch,'executed_calls':0,
         'scope':'Only supplied known-creator pages; not all advertisers, paid contracts or a brand share-of-voice denominator',
         'provenance':provenance}
target.mkdir()
for name,rows,fields in [('brand-evidence',evidence,['creator_user_id','note_id','classification','observed_labels','source_numbers','collected_at','manual_review_required']),
                         ('creator-roster',[{'creator_user_id':creator,'matched_note_count':len(notes),'note_ids':notes,'manual_review_required':True} for creator,notes in sorted(roster.items())],['creator_user_id','matched_note_count','note_ids','manual_review_required'])]:
    (target/(name+'.json')).write_text(json.dumps(rows,ensure_ascii=False,indent=2),encoding='utf-8')
    with (target/(name+'.csv')).open('x',encoding='utf-8-sig',newline='') as output:
        writer=csv.DictWriter(output,fieldnames=fields);writer.writeheader();writer.writerows({k:cell(v) for k,v in row.items()} for row in rows)
(target/'coverage.json').write_text(json.dumps(summary,ensure_ascii=False,indent=2),encoding='utf-8')
for index,(raw,manifest_raw) in enumerate(saved):
    (target/('source-'+str(index+1)+'.json')).write_bytes(raw)
    (target/('manifest-'+str(index+1)+'.json')).write_bytes(manifest_raw)
print(str(target/'creator-roster.csv'))
```

```bash
python3 brand_roster.py pgy_cases.py brand-input.json competitor-review
```

`brand_roster.py` 只在本地运行，不产生收费请求。脚本拒绝混合条件和跨博主的同笔记归属冲突，保留原件、时间、请求 ID 和来源编号。同一笔记的不同品牌记录隔离为冲突；缺失品牌记为未知；别名只用你明确填写的标签，不自动归并。CSV 防公式注入，JSON 保留原值，已有输出目录不会被覆盖。原件哈希只关联本地资料，不认证平台来源。

把生成的文件当作待复核的工作底稿，不当作已证实的合同清单。关键不是把每一格填满，而是把准备联系的人、相关案例和还要问的问题对应起来。