> 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.

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

> Build a Xiaohongshu creator shortlist with xiaohongshu.pgy.get_blogger_list, export deduplicated userId rows via pgy_candidates.py, and attach profiles, audiences, cooperation cases, and performance metrics only to shortlisted creators.

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](https://pgy.xiaohongshu.com/)

## Where does each shortlist column come from?

| Decision                                        | Evidence in this workflow                                              | Next action                                                                                                                           |
| ----------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Which creators fit the brief?                   | Saved candidate pages with real userId, returned prices and metrics    | Export 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 distributions                    | [Review audience evidence](/faq/xiaohongshu-audience-quality); distributions do not certify individual followers or buyers            |
| Has the creator worked with a relevant brand?   | Selected cooperation cases and exact brandName labels                  | [Export and review cases](/faq/xiaohongshu-sponsored-notes); missing labels stay unknown, conflicting duplicate evidence stops export |
| What is organic versus all-traffic performance? | Explicit traffic scope and matched note IDs                            | [Compare the documented scopes](/faq/xiaohongshu-organic-traffic); keep unmatched observations separate                               |
| What happened after our campaign?               | A fixed target list, observation times and exported public/PGY metrics | [Build a scoped report](/faq/xiaohongshu-report-availability), not a complete attribution claim                                       |
| Is interest in a topic changing?                | A separate keyword-index query and its returned dates                  | [Read keyword trends](/faq/xiaohongshu-keyword-index); 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

```bash
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:

```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_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](/faq/xiaohongshu-creator-filters), or start from [similar creators](/faq/xiaohongshu-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:

```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_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](/faq/xiaohongshu-audience-quality).

## 5. Review cooperation cases, not just account totals

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

```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":"<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](/guides/douyin-creator-collaboration-review). 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](https://beatapi.io/pricing). 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](/faq/xiaohongshu-sponsored-notes) · [Organic traffic scope](/faq/xiaohongshu-organic-traffic) · [Question index](/faq/xiaohongshu)

## 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](https://beatapi.io/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:

```json
[{"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.

```python
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](/faq/xiaohongshu-audience-quality).

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](https://beatapi.io/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:

```json
[{"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.

```python
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.