Skip to navigation

How do I turn a Xiaohongshu collaboration brief into filters and a reviewable creator list?

To turn a collaboration brief into a reviewable creator list, filter the Pugongying creator list with xiaohongshu.pgy.get_blogger_list. Put content direction and creator location under blogger, audience size and location under fans, and image or video quotes under coop. Review the first page, then open the recent work of the creators you select.

For example, for an image-post beauty collaboration in Shanghai, narrow the list by content direction, creator location, follower range and image-post quote. If the requirement is about Shanghai viewers, use the fans.location condition instead of creator location.

Translate the brief into inputs

RequirementInputReview afterward
Content directionblogger.content_tagWhether recent work fits the topic
Creator locationblogger.locationSuitability for the shoot or event
Follower count and locationfans.count, fans.locationFit with the audience brief
Image/video quotecoop.pic_price, coop.video_priceReturned quote, unit and collaboration conditions
Recent collaboration industrycoop.industrySpecific cases and brand context

Call data:xiaohongshu.pgy.get_blogger_list with the conditions nested under blogger, fans and coop. Review the first page for relevance before expanding the collection.

To hand the task to an assistant with the tools configured, use a prompt such as:

Find one candidate page for this image-post brief, keeping account IDs, actual quotes and sources. Distinguish creator conditions from follower conditions and list recent work and profile checks for relevant accounts.

A returned record is a candidate, not a confirmed fit. For each candidate, keep the selection reason and the open checks, so the later content, audience and case review answers a specific question.

A filter request to adapt

The numbers in the request below are illustrative inputs, not recommended industry thresholds. Check the current contract and price with Inspect before you run the request.

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":{"blogger":{"content_tag":["美妆"],"location":["上海"]},"fans":{"count":{"min":10000,"max":50000}},"coop":{"pic_price":{"max":5000}},"column":"fansCount","sort":"desc","page_num":1,"page_size":20}}' \
-o xiaohongshu-creators-page-1.json

Which conditions are different?

SelectionInput
Creator locationblogger.location, an array of strings
Audience locationfans.location, not the creator’s location
Creator note-keyword searchkeyword with search_type: 1, the default
Nickname searchkeyword with search_type: 0
Image-note / video quoted pricemin/max under coop.pic_price / coop.video_price
Recent cooperation industrycoop.industry, including literal enum values 美妆个护 and 3c及电器

Creator content categories (blogger.content_tag) and cooperation industries (coop.industry) are different: a technology creator has not necessarily worked with an electronics brand recently. The content_tag schema gives strings and selected examples, not an exhaustive value dictionary. When a combination of filters returns nothing, the intersection of the filters is empty; the empty result does not prove that the platform has no suitable creators.

How do beauty and tech briefs differ?

For skincare, start with a verified beauty content tag and add coop.industry: "美妆个护" if the brief requires recent beauty deals. For a tech review, search note keywords such as 手机测评 (“phone reviews”) and add coop.industry: "3c及电器" when recent electronics collaborations matter. Save the filters with each shortlist, then review actual posts to see whether each creator shows skincare use or hands-on device testing. When you do not know the tag value, start with keywords.

Can I export the entire creator directory?

No. page_num accepts 1–250 and page_size 1–20, and the documented visible range is the first 5000 records. Keep conditions and ordering unchanged while paging, and expect duplicates when results change between pages. The action’s response structure places creators at data.data.kols keyed by userId, although the public catalog has no full output schema. The linked shortlist guide exports saved pages with data.data.kols and userId, preserving failures, duplicates, and quote changes. total is a paging cap, not the number of matching creators.

Build a candidate shortlist · Find similar creators

Sources: free Inspect of data:xiaohongshu.pgy.get_blogger_list. A returned quote is not a guaranteed negotiated price.

How do I prioritize creators who respond to invitations and stay active?

For a discovery shortlist, set coop.reply_48h_ratio.min: 80 and flags.exclude_low_active: true, and sort by inviteReply48hNumRatio descending. coop.reply_48h_ratio takes percentage points from 0 to 100: 80 means 80%, not 0.8. 80 is an example threshold, not a universal recommendation. The low-activity creator filter and the active-follower metric describe different populations.

Save the request below as responsive-creators-request.json and replace the keyword with your campaign’s topic:

{"action":"xiaohongshu.pgy.get_blogger_list","params":{"keyword":"咖啡","search_type":1,"coop":{"reply_48h_ratio":{"min":80}},"flags":{"exclude_low_active":true},"column":"inviteReply48hNumRatio","sort":"desc","page_num":1,"page_size":20}}

After the price is approved, save one complete response and the HTTP status:

curl -sS https://api.beatapi.io/v1/social-data/call -H "Authorization: Bearer $BEATAPI_API_KEY" -H 'Content-Type: application/json' --data-binary @responsive-creators-request.json -o responsive-creators-page-1.json -w '%{http_code}\n'

Create responsive-manifest.json as an array with one record: the exact action and params from the request, the observed HTTP status, your timezone-aware collection time and response_file: "responsive-creators-page-1.json". The format matches section 7 of the candidate-library guide. Run the guide’s complete pgy_candidates.py locally:

python3 pgy_candidates.py responsive-manifest.json responsive-review

Read the coverage report before the candidate CSV: gateway errors, a failed business envelope and a null list are not an empty shortlist. pgy_candidates.py keeps the requested filters, the source bytes, the timestamps and every creator observation. The output is a candidate list returned under those conditions, not independently verified per-creator reply percentages and not an “easy to reach” badge. Do not add guessed invite_reply_rate, active_days_7d, is_active or easy_to_reach columns. For later pages, keep every condition and the sort order, use the next consecutive page number and stay within the helper’s five-page limit; stop on an empty, repeated or error result or at your approved limit.

Estimate the list retrieval cost from the actual pages and current pricing. pgy_candidates.py accepts up to five pages per batch, and deduplication can reduce the row count. The historical 48-hour condition helps choose whom to review; the condition does not guarantee a reply or availability.

Can I export each creator’s exact active days and reply rate?

No. data:xiaohongshu.pgy.get_blogger_data_summary lists seven-day activity and 48-hour invitation responsiveness as service metrics, with business: 0 for daily-note scope and 1 for cooperation-note scope. The public documentation does not name the service-metric JSON keys or numeric scales, and does not establish easy-to-reach or active badge fields; the documented response structure does not supply those field mappings either. This page therefore stops at the filter-to-candidate workflow and does not export per-creator badges or activity metrics. Do not buy repeated null summaries, and do not relabel active-follower ratios as creator activity.

For outreach planning, review each candidate’s recent content and actual cooperation availability, then record the campaign deadline and the response to an authorized invitation in your own campaign sheet. Keep the observed response separate from the platform’s historical selection criterion. The scripts on this page send no invitations.