Skip to navigation

How do I shortlist Xiaohongshu creators and review their audience and recent cooperation?

To build a Xiaohongshu creator shortlist, fetch one Pugongying (PGY) directory page with data:xiaohongshu.pgy.get_blogger_list, filtered by content, location and price. For each creator you select, pass the returned userId to the audience and cooperation-note lookups in steps 4 and 5. For each shortlisted creator, record the selection reason, the source and what the team still needs to confirm.

Suppose you are planning an in-person coffee machine demo in Shanghai. Check whether each creator can attend, has made photo tutorials and quotes within budget. If a creator’s content fits but the audience location is not checked yet, mark the audience lookup as pending. When two creators quote similar prices, review which creator has shown a comparable product in use. Confirm availability, the final quote and usage rights through the collaboration process. Pugongying

Where does each shortlist column come from?

DecisionEvidence in this workflowNext action
Which creators fit the brief?Saved candidate pages with real userId, returned prices and metricsExport the shortlist with the section 7 exporter, then review content fit; list position is not an endorsement
Does the audience fit?Separately retrieved creator audience distributionsReview audience evidence; distributions do not certify individual followers or buyers
Has the creator worked with a relevant brand?Selected cooperation cases and exact brandName labelsExport and review cases; missing labels stay unknown, conflicting duplicate evidence stops export
What is organic versus all-traffic performance?Explicit traffic scope and matched note IDsCompare the documented scopes; keep unmatched observations separate
What happened after our campaign?A fixed target list, observation times and exported public/PGY metricsBuild a scoped report, not a complete attribution claim
Is interest in a topic changing?A separate keyword-index query and its returned datesRead keyword trends; an index is not search people or sales

Track data requests, creator payments and promotion costs separately in the budget. The request counts on this page cover data lookups only.

1. Define conditions and execution limits

Decide the content type, location, follower range and quoted-price range. Creator location differs from audience location, and content category differs from recent cooperation industry. A first run can use one candidate page, then one creator’s detail, audience and one case page. The first-run limits control spending; the limits are not quality thresholds.

2. Inspect for free and fetch candidates

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

Confirm the nested inputs and the price in the Inspect result before the paid call. The example request searches note keywords for coffee with an illustrative follower range:

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_list","params":{"keyword":"咖啡","search_type":1,"fans":{"count":{"min":10000,"max":50000}},"page_num":1,"page_size":20}}' \
-o creator-candidates-page-1.json

search_type 1 finds creators by note keywords, not by exact nickname; use 0 for nickname search. Add location and quoted-price conditions, or start from similar creators when you have a seed creator.

3. Review actual output and retain candidates

The public catalog has no fixed output schema, but the response structure places creators at data.data.kols keyed by userId, and section 7 provides an exporter for saved pages. Deduplicate real user IDs and keep the filters, ordering, page, time, and request ID. Do not construct IDs from names or invent missing metrics.

For further pages, keep the same conditions and order, increment page_num from 1 and keep page_size at most 20. The allowed maximum is 250 pages, and the documented visible range is 5000 records, which is not the complete creator directory. Stop on repeated pages, errors or the approved page limit.

4. Inspect only selected profiles and audiences

Before expanding, Inspect data:xiaohongshu.pgy.get_blogger_detail and data:xiaohongshu.pgy.get_blogger_fans_profile separately. After the price is approved, call both actions with the selected creator’s verified user ID:

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_detail","params":{"user_id":"<selected_user_id>"}}' \
-o selected-creator-detail.json
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_fans_profile","params":{"user_id":"<selected_user_id>"}}' \
-o selected-creator-audience.json

The detail and audience requests are separate from the list export. The audience FAQ lists the documented profile distribution fields; not every creator returns every field. Keep estimate labels where present. Audience profiles are not authenticity verdicts.

5. Review cooperation cases, not just account totals

Inspect data:xiaohongshu.pgy.get_blogger_notes, then retrieve one approved page of cooperation notes:

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":"<selected_user_id>","note_type":3,"order_type":1,"page_number":1,"page_size":8}}' \
-o selected-creator-sponsored-notes.json

note_type 3 selects cooperation notes. The default advertise_switch 1 includes all traffic. If the evaluation goal is organic performance, specify an organic scope; sponsorship and paid traffic are different things. Keep the examples and review content relevance manually; the AI must not fill in absent sources or metrics.

If the campaign also needs Douyin creators, use the Xingtu collaboration workflow. Key the combined shortlist by platform and creator ID. Keep each quote, audience definition and representative post with its source. Link accounts that belong to the same person, and confirm each account’s terms separately.

6. Deliver evidence and count calls

Suggested local columns: user ID, selection conditions, actual profile information, example sources, audience evidence and unresolved items. Reconfirm quotes before negotiation; a score must not hide missing evidence.

One candidate page plus one creator’s detail, audience and case page takes four platform calls. Price each action with the pricing page. Reviewing M creators with all three follow-ups takes 1 + 3M calls; extra pages and model analysis are billed separately. A 20-creator candidate page is one call; the call does not verify each creator’s complete profile.

The section 7 exporter exports the documented fields automatically; profile expansion and relevance decisions stay separate manual reviews. A failed page is not an empty candidate set; review saved results before paying for repeated queries.

Cooperation-case parameters · Organic traffic scope · Question index

7. Turn saved candidate pages into a reviewable creator library

BeatAPI preserves the Pugongying envelope directly under data, placing creators at data.data.kols[] with userId as the deduplication key. pgy_candidates.py extracts the documented name, redId, location, follower count, image/video quotes, reading/engagement medians, and estimated image CPM fields without inventing a third-party schema. The request contract needs no view=full parameter. pgy_candidates.py preserves values as returned and does not turn returned metrics into guaranteed performance or final negotiated prices.

For the coffee query above, keep the same filters and ordering for at most five pages; pgy_candidates.py accepts no more than five. Plan by actual page requests at current pricing. Five pages return at most 100 positions before filtering and duplicates, not 100 guaranteed creators. Stop on failed, repeated, or empty pages and review what was saved; an empty page does not mean the entire directory is empty. The documentation describes total as a paging cap, not a hit count.

Create a manifest that lists the full responses you actually saved. Add a page entry only for a call actually made, with the actual HTTP status and a timezone-aware collection time. The entry below shows the format and is not recorded evidence:

[{"action":"xiaohongshu.pgy.get_blogger_list","params":{"keyword":"咖啡","search_type":1,"fans":{"count":{"min":10000,"max":50000}},"page_num":1,"page_size":20},"http_status":200,"collected_at":"2026-11-16T10:00:00Z","response_file":"creator-candidates-page-1.json"}]

Save the script below as pgy_candidates.py. pgy_candidates.py makes no API calls, enforces the five-page review limit and unchanged filters, keeps real gateway error envelopes and inner PGY failures, deduplicates by userId, and stores every observation separately so changed quotes are not discarded. Contract basis: the documented xiaohongshu.pgy.get_blogger_list response structure.

import csv,datetime,hashlib,json,pathlib,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 1<=len(entries)<=5:raise ValueError("This review helper accepts 1-5 recorded pages")
columns=["name","redId","location","fansNum","picturePrice","videoPrice","clickMidNum","interMidNum","estimatePictureCpm"]
creators={};pages=[];blobs=[];request_ids=set();filters=None;previous_time=None;signatures=set();observations=[]
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
for page_index,entry in enumerate(entries,1):
if entry.get("action")!="xiaohongshu.pgy.get_blogger_list":raise ValueError("Wrong manifest action")
params=entry["params"]
if params.get("page_num")!=page_index or type(params.get("page_num")) is not int:raise ValueError("Record consecutive pages starting at 1")
if params.get("page_size")!=20 or type(params.get("page_size")) is not int:raise ValueError("This helper keeps page_size=20")
current={key:value for key,value in params.items() if key!="page_num"}
if filters is None:filters=current
if current!=filters:raise ValueError("Keep every filter and sort unchanged")
stamp=entry["collected_at"];dt=datetime.datetime.fromisoformat(stamp.replace("Z","+00:00"))
if dt.tzinfo is None or (previous_time is not None and dt<=previous_time):raise ValueError("Use increasing timezone-aware request times")
previous_time=dt
http=entry.get("http_status")
if type(http) is not int or not 100<=http<=599:raise ValueError("Actual HTTP status required")
source=pathlib.Path(entry["response_file"])
if not source.is_absolute():source=manifest.parent/source
raw=source.read_bytes();r=json.loads(raw);error=r.get("error")
if error is not None:
if not isinstance(error,dict) or http<400:raise ValueError("Invalid error envelope")
request_id=error.get("request_id")
else:
if http!=200 or r.get("action")!="xiaohongshu.pgy.get_blogger_list" or r.get("status")!="succeeded":raise ValueError("Unexpected success response")
request_id=r.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)
filename="page-"+str(page_index)+".json";digest=hashlib.sha256(raw).hexdigest();blobs.append((filename,raw))
page={"page_num":page_index,"params":params,"request_id":request_id,"collected_at":stamp,"http_status":http,
"source_file":str(source),"archived_file":filename,"sha256":digest,"state":"gateway_failed","records":0}
if error is not None:page["error_code"]=error.get("code")
else:
envelope=r.get("data")
if not isinstance(envelope,dict):raise ValueError("Missing PGY envelope")
if envelope.get("success") is False:page["state"]="pgy_business_failed"
elif envelope.get("success") is not True:raise ValueError("Explicit PGY success required")
elif envelope.get("data") is None:page["state"]="no_payload"
else:
data=envelope["data"]
if not isinstance(data,dict) or not isinstance(data.get("kols"),list):raise ValueError("Expected documented kols array")
ids=[]
for position,creator in enumerate(data["kols"]):
if not isinstance(creator,dict):raise ValueError("Invalid creator object")
uid=creator.get("userId")
if not isinstance(uid,str) or not uid.strip() or "<" in uid or ">" in uid:raise ValueError("Real userId required")
ids.append(uid)
observations.append({"userId":uid,"page_num":page_index,"item_index":position,"request_id":request_id,"creator":creator})
if uid not in creators:
creators[uid]={"userId":uid,**{key:creator.get(key) for key in columns},"first_page":page_index,
"first_request_id":request_id,"first_collected_at":stamp,"observation_count":0,
"review_decision":"","fit_evidence":"","quote_rechecked_at":""}
creators[uid]["observation_count"]+=1
signature=tuple(ids)
page.update({"state":"empty" if not ids else "available","records":len(ids),
"repeated_ordered_ids":bool(ids) and signature in signatures,"reported_total":data.get("total")})
if ids:signatures.add(signature)
pages.append(page)
report={"pages":pages,"filters":filters,"unique_creator_ids":len(creators),"returned_occurrences":len(observations),
"deduplication":"First observation retained in CSV; all variants preserved in observations.jsonl",
"coverage":"Only recorded pages, not entire directory. reported_total is not the candidate count."}
target.mkdir()
with (target/"creators.csv").open("x",encoding="utf-8-sig",newline="") as output:
writer=csv.DictWriter(output,fieldnames=["userId",*columns,"first_page","first_request_id","first_collected_at","observation_count","review_decision","fit_evidence","quote_rechecked_at"])
writer.writeheader();writer.writerows({key:cell(value) for key,value in row.items()} for row in creators.values())
with (target/"observations.jsonl").open("x",encoding="utf-8") as output:
for row in observations:output.write(json.dumps(row,ensure_ascii=False)+"\n")
for filename,raw in blobs:(target/filename).write_bytes(raw)
(target/"coverage.json").write_text(json.dumps(report,ensure_ascii=False,indent=2),encoding="utf-8")
print(str(target/"creators.csv"))

Run python3 pgy_candidates.py creator-manifest.json creator-library-1. Review coverage.json first: coverage.json lists page states, hashes, request IDs, returned occurrences and unique creator IDs. A failed page is not an empty success. Record transport failures without JSON in a separate collection log, not as an invented result row. pgy_candidates.py refuses an existing output directory.

Open creators.csv and fill review_decision and fit_evidence after checking content relevance. Each field keeps the returned representation: nested values stay JSON text, and missing values stay blank. The first observation is the CSV baseline; observation_count and observations.jsonl show duplicate or changed entries. Do not sort textual quotes as numeric amounts before verifying units and format. Only shortlisted IDs should incur extra profile or case requests. The export does not contact creators or commit a campaign budget. To compare several keywords, create a separate evidence package per keyword, and join by userId only after each search context is saved.

Use quotes, audience evidence and recent work to choose the next round

For a coffee event in Shanghai, start with creators who have covered café visits, then review picturePrice for photo notes. Record videoPrice separately for video proposals. Give each row a creator ID, format, original quote, confirmed currency and unit, collection time and recent example. Compare only quotes with matching terms, and flag the details still needed.

Run the section 4 lookups for shortlisted creators. Record the actual location or interest segment, the reported value and the measurement date where available. City distribution and interest distribution each describe a separate group. If the brief requires people in Shanghai who are interested in coffee, leave the combined segment open until you have matching evidence. See the audience FAQ.

For example, keep a creator whose café-visit example, photo-note quote and location evidence fit the brief. For another creator with relevant work but only a video quote, record “photo-note quote needed.” Hand off the examples, confirmed details and open questions together.

8. Attach performance evidence only to manually shortlisted IDs

After reviewing the candidate CSV, put the exact value shortlist in review_decision for each chosen row and leave other rows unchanged. join_pgy_performance.py reads the shortlist selection, never requests data and never changes the original roster. For an approved performance lookup, call xiaohongshu.pgy.get_blogger_notes_rate with explicit business/date_type/note_type/advertise_switch values. Every candidate in one comparison must use the same scope.

The performance source establishes data.data.impMedian, readMedian, interactionMedian and impMedianBeyondRate. Keep the raw representations; a peer percentile is not an audience share. The performance description names no other completion or engagement rate keys, so the exporter creates none. Plan one additional performance request per selected creator at current pricing.

Save each actual request and result pair in performance-manifest.json, with the true HTTP status and time. The entry below shows the request-record format and is not recorded evidence:

[{"action":"xiaohongshu.pgy.get_blogger_notes_rate","params":{"user_id":"YOUR_SHORTLISTED_ID","business":1,"date_type":1,"note_type":3,"advertise_switch":0},"http_status":200,"collected_at":"2026-11-16T10:00:00Z","response_file":"creator-performance.json"}]

Save the script below as join_pgy_performance.py. The script builds a companion table keyed by userId and keeps every shortlisted creator, including creators not yet queried and creators whose saved request failed. The script refuses unselected IDs and mixed scopes, keeps missing metrics missing and records hashes of the raw evidence. Each creator is bound to the actual request manifest; the script assumes no undocumented response identity field.

import csv,datetime,hashlib,json,pathlib,sys
roster,manifest,target=map(pathlib.Path,sys.argv[1:4])
with roster.open(encoding="utf-8-sig",newline="") as f:all_rows=list(csv.DictReader(f))
selected={}
for row in all_rows:
if row.get("review_decision")!="shortlist":continue
uid=row.get("userId")
if not uid or not uid.strip() or uid in selected:raise ValueError("Distinct shortlisted userId required")
selected[uid]=row
if not selected:raise ValueError("Mark at least one reviewed creator as shortlist")
entries=json.loads(manifest.read_text(encoding="utf-8"))
if not isinstance(entries,list):raise ValueError("Manifest must be an array")
metrics=["impMedian","readMedian","interactionMedian","impMedianBeyondRate"]
observed={};scope=None;request_ids=set();evidence=[]
for entry in entries:
if entry.get("action")!="xiaohongshu.pgy.get_blogger_notes_rate":raise ValueError("Wrong action")
params=entry["params"];uid=params.get("user_id")
if uid not in selected or uid in observed:raise ValueError("Only one result per shortlisted ID")
if set(params)!={"user_id","business","date_type","note_type","advertise_switch"}:raise ValueError("Record every scope explicitly")
for key,values in {"business":(0,1),"date_type":(1,2),"note_type":(1,2,3),"advertise_switch":(0,1)}.items():
if type(params[key]) is not int or params[key] not in values:raise ValueError("Invalid scope")
current={key:value for key,value in params.items() if key!="user_id"}
if scope is None:scope=current
if current!=scope:raise ValueError("Do not compare different content, time or traffic scopes")
stamp=entry["collected_at"]
if datetime.datetime.fromisoformat(stamp.replace("Z","+00:00")).tzinfo is None:raise ValueError("Timezone required")
http=entry.get("http_status")
if type(http) is not int or not 100<=http<=599:raise ValueError("Record HTTP status")
path=pathlib.Path(entry["response_file"])
if not path.is_absolute():path=manifest.parent/path
raw=path.read_bytes();r=json.loads(raw);error=r.get("error")
if error is not None:
if not isinstance(error,dict) or http<400:raise ValueError("Invalid error envelope")
rid=error.get("request_id")
else:
if http!=200 or r.get("action")!=entry["action"] or r.get("status")!="succeeded":raise ValueError("Unexpected response")
rid=r.get("request_id")
if not isinstance(rid,str) or not rid.strip() or rid in request_ids:raise ValueError("Distinct request IDs required")
request_ids.add(rid)
values={key:None for key in metrics};state="gateway_failed"
if error is None:
envelope=r.get("data")
if not isinstance(envelope,dict):raise ValueError("PGY envelope required")
if envelope.get("success") is False:state="pgy_business_failed"
elif envelope.get("success") is not True:raise ValueError("Explicit PGY success required")
elif envelope.get("data") is None:state="no_payload"
else:
data=envelope["data"]
if not isinstance(data,dict):raise ValueError("Expected performance object")
values={key:data.get(key) for key in metrics}
state="available" if all(value is not None for value in values.values()) else "partial_metrics"
observed[uid]={"userId":uid,"performance_state":state,**values,"performance_request_id":rid,"performance_collected_at":stamp}
evidence.append({"userId":uid,"params":params,"request_id":rid,"source_file":str(path),"sha256":hashlib.sha256(raw).hexdigest(),"http_status":http})
rows=[]
for uid in selected:
rows.append(observed.get(uid,{"userId":uid,"performance_state":"not_requested",**{key:None for key in metrics},"performance_request_id":"","performance_collected_at":""}))
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
target.mkdir()
with (target/"performance.csv").open("x",encoding="utf-8-sig",newline="") as f:
writer=csv.DictWriter(f,fieldnames=list(rows[0]));writer.writeheader();writer.writerows({key:cell(value) for key,value in row.items()} for row in rows)
(target/"evidence.json").write_text(json.dumps({"scope":scope,"records":evidence,"shortlisted":len(selected),"requested":len(observed),"identity_binding":"Actual request manifest, not independently returned creator identity"},ensure_ascii=False,indent=2),encoding="utf-8")
print(str(target/"performance.csv"))

Run python3 join_pgy_performance.py creator-library-1/creators.csv performance-manifest.json creator-performance-review-1. Keep the original roster, the manifest and the raw response files with performance.csv and evidence.json. An empty manifest marks every selected creator not_requested; not_requested does not mean the creator has no performance. Missing results stay in the denominator of your review.

The example scope is sponsored content, last 30 days, image + video, and organic traffic. Do not compare the example scope directly with a default daily-content, all-traffic record. Median reading is not total campaign reach, a peer percentile is not a guaranteed ranking for your product, and missing fields are not zero. Reconfirm content fit, availability, and commercial terms before a separate outreach decision. Contract basis: the documented xiaohongshu.pgy.get_blogger_notes_rate response fields; join_pgy_performance.py runs locally and never queries APIs or contacts creators.

Which creator-page evidence should I review first?

Start candidate selection with confirmed picturePrice, videoPrice and examples. For shortlisted creators, use the same creator user_id for details and audience evidence. Keep dates, content types and promotion conditions with performance material. Keep growth, service and cost modules open until an actual response provides matching values. If your brief needs a local audience, verify location evidence and relevant recent work first.