탐색으로 건너뛰기

Which creators on my shortlist have worked with a competing brand?

To find which creators on your shortlist have worked with a competing brand, request each creator’s cooperation cases with xiaohongshu.pgy.get_blogger_notes, passing the creator’s user_id and note_type:3. Check the returned brand labels, then list the matched creators with their notes and sources. Before outreach, open the selected notes to see whether the work is relevant to your product, and add availability and exclusivity to the questions you confirm with each creator.

If you only have the competitor’s brand name, find candidate creators with public search first, then look up their cases. Report which creators and case pages you checked.

What will I have, and how does it help me decide whom to contact?

The workflow produces two tables: the creators in your sample with matching brand cases, and the underlying notes to find on each creator’s profile and review. The tables contain note IDs, not working share links. Missing brands and contradictory records stay separate from the matched list.

The table below shows how to interpret typical sample outcomes (illustrative placeholders, not real creator records):

CandidateWhat this round foundBefore making contact
Creator ATwo cases carry the target brand labelReview product fit and creative style; if interested, ask about availability, exclusivity and the current quote.
Creator BCases returned, but the brand is blankKeep as unresolved, not “has never worked with a competitor.”
Creator CTwo observations give different brands for the same noteResolve the note and source first; do not count it as confirmed competitor work.

Competitor experience can be relevant expertise or a reason to ask about exclusivity; competitor experience is not an automatic rejection or a ranking score. The tables contain no contract amount, actual campaign spend or conversions, and a current quote does not tell you what a previous campaign paid.

What if you only have the competitor brand name?

Search the competitor’s name and confirmed aliases with the note search guide, review the actual product context and remove unrelated namesakes. List the relevant authors as candidates. The search shows only that these authors mentioned the brand; add cooperation evidence by checking each author’s creator cases with the workflow on this page.

Brand search gives a research starting point. Counting declared sponsored posts in search results, or confirming the declared brand of one note, still needs search sponsorship flags and single-note brand output that are not yet established. Keep those gaps visible, and do not report brand-keyword matches as a sponsorship rate.

1. Choose the people and brand scope for this round

Use the stable creator IDs from your existing shortlist, not IDs built from nicknames. If you need a shortlist first, build one with content and budget criteria, then come back to check the selected creators.

Keep every creator in your original candidate sheet and add five columns by hand: round status, representative case, content fit, questions to ask and outreach decision. The five columns are your working notes, not generated scores. The matched roster supplements the candidate sheet and does not replace it. Keep candidates with empty pages, no matches or failed queries, and mark each one as no match in this round or unresolved.

Write down the creators, the competitor brand and your maximum page budget. Chinese names, English names and sub-brands can appear as separate labels. Group only returned labels that you have confirmed by hand to belong to the same target brand; similar spelling is not enough.

For a first pass, read one page per creator, then add pages only for creators worth investigating further. The example request orders cases by reads. If your question is about recent partnerships, use newest order instead and keep that order for the whole round. Neither first page is a complete history.

2. Review cooperation cases before buying every other report

Request one page of cooperation cases for one known creator. Do not add audience profiles, full quotes and campaign reports for everyone at once; request those reports only when they answer a specific follow-up question about a creator you may contact.

Use the current case-page price on the pricing page. Twenty candidates at one page each is twenty case-page requests; add discovery, details, extra pages or model analysis only where needed. Reuse saved originals, and check whether the first batch already answers the outreach question.

The implementation sections below give the request and two complete local scripts. Save each actual response with its request record: creator ID, filters, page and collection time. The creator ID records whom you queried; the ID is not independent platform proof of authorship, so check each note’s author during review.

3. Turn the brand leads into a list you can review

Run pgy_cases.py on each page first to see the actual brand labels. Put the labels you have confirmed into the brand configuration, then merge the pages across creators with brand_roster.py. A repeated note counts once, and a conflicting brand observation is not resolved by whichever page loaded last.

Review the outputs in this order:

  1. Check what actually matched. coverage.json separates matches, unknown brands, conflicts and other labels. Zero matches means none in the supplied sample, not that the brand has never sponsored anyone and not that the creator has no partnership history.
  2. Read the relevant notes. Take the note ID from brand-evidence.csv and the title and date from the single-page cases.csv, find the note on the creator’s profile, and check the note’s ID, author and brand. If you cannot find the note, leave the note unresolved. Do not build a share link without its access token, and do not buy a detail lookup automatically. A returned brand label is a source claim, not a contract or a payment receipt.
  3. Prepare your outreach shortlist. creator-roster.csv lists only matched creators and their notes, not candidates with empty pages or failures. Join creator-roster.csv to your existing shortlist by creator ID to recover names and your selection reasons, then choose the outreach order by hand. Do not join separate accounts by nickname.

The original records and the JSON versions of both tables stay available for investigating a discrepancy. Import IDs as text in spreadsheets. Every row needs human review; the scripts do not contact creators or commit a campaign budget.

4. What should I ask before agreeing to a collaboration?

Check one or two representative notes for product and creative fit, not just the number of past partnerships. Then confirm availability, whether the creator accepts your category, competitor exclusivity, deliverables and the current quote. To examine case performance, retrieve exposure and read counts for confirmed notes; a brand label says nothing about results.

Mark missing brands, conflicts and failed pages as unresolved in the original candidate sheet, and record which step is blocked. A failed page stops the parser, so a missing output row is not a verdict on that creator, and missing evidence is not a negative verdict. Each additional query should resolve a specific question; do not run every available action for every creator.

Implementation: collect one cooperation-case page

data:xiaohongshu.pgy.get_blogger_notes selects cooperation cases with note_type: 3. The example uses order_type: 2 for read order and advertise_switch: 1 for all traffic. Replace user_id with a verified shortlist ID, and use a different filename for each creator.

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

Each parameter below answers a different question:

ChangeParameter
Newest, most read or most engagedorder_type 1, 2 or 3 respectively
All traffic or organic onlyadvertise_switch 1 or 0; separate from whether a note is sponsored
Cross-platform cooperation onlyis_third_platform: 1; default 0 leaves that dimension unrestricted
Next pagepage_number, not the creator directory’s page_num; allowed 1–1000 does not mean those pages exist
Page sizepage_size 1–8; this example uses 8

note_type 1, 2 and 4 mean image, video and all; each is an alternative to 3, so one field cannot combine “sponsored videos”. For content_tag and feature_tag, use tags from actual creator details, not an invented full dictionary. Keep filters and ordering unchanged while paging, and stop on an empty or repeated full page, an error or the approved limit. Do not buy the V2 action automatically; the V2 output structure differs.

Save a case-request.json for each actual response. The example below shows the format; replace the time, ID and page with the actual call details:

{"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"}

Implementation: review each page, then merge the brand shortlist

Save the script below as pgy_cases.py. pgy_cases.py takes a complete BeatAPI response, not a trimmed preview. The response places cooperation cases in data.data.list[], keyed by noteId; pgy_cases.py validates saved responses locally against that structure.

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"))
python3 pgy_cases.py creator-sponsored-notes.json case-request.json case-review-1

Inspect the page’s cases.csv and review.json to confirm the returned labels. readNum is reads; thirdReadUserNum is described as off-site readers, not guaranteed store visits. isAdvertise and isVideo keep their original values and types instead of turning arbitrary strings into booleans, so review contradictory flags. Conflicting duplicate evidence within a page stops output. total is a filter-dependent case count, not the creator-directory paging cap.

Create brand-input.json with your confirmed exact labels and each saved response/request pair. Replace the placeholder brand names below with your confirmed labels; file paths are relative to brand-input.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"}]}

Save brand_roster.py beside the single-page script:

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'))
python3 brand_roster.py pgy_cases.py brand-input.json competitor-review

brand_roster.py runs locally and makes no paid calls. The script rejects mixed conditions and a note attributed to different creator manifests, and keeps originals, times, request IDs and source numbers. Conflicting brands are quarantined, missing labels stay unknown, and aliases are only the labels you supply explicitly. CSV cells are formula-escaped, JSON keeps the values as returned, and existing output directories are never overwritten. File hashes link local records; the hashes do not authenticate the platform.

Treat the result as a review worksheet, not a confirmed contract register. The useful outcome is a clear link between the creators you might contact, relevant examples and the questions still to ask; do not fill empty cells with guesses.