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):
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:
- Check what actually matched.
coverage.jsonseparates 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. - Read the relevant notes. Take the note ID from
brand-evidence.csvand the title and date from the single-pagecases.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. - Prepare your outreach shortlist.
creator-roster.csvlists only matched creators and their notes, not candidates with empty pages or failures. Joincreator-roster.csvto 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.
Each parameter below answers a different question:
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:
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.
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:
Save brand_roster.py beside the single-page script:
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.

