> 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 turn a Xiaohongshu collaboration brief into filters and a reviewable creator list?

> Map a Xiaohongshu collaboration brief to nested blogger, fans, coop, and flags filters in xiaohongshu.pgy.get_blogger_list, export saved pages via pgy_candidates.py, and keep 5,000-row and metric limits explicit.

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

| Requirement                   | Input                                | Review afterward                                  |
| ----------------------------- | ------------------------------------ | ------------------------------------------------- |
| Content direction             | `blogger.content_tag`                | Whether recent work fits the topic                |
| Creator location              | `blogger.location`                   | Suitability for the shoot or event                |
| Follower count and location   | `fans.count`, `fans.location`        | Fit with the audience brief                       |
| Image/video quote             | `coop.pic_price`, `coop.video_price` | Returned quote, unit and collaboration conditions |
| Recent collaboration industry | `coop.industry`                      | Specific 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.

```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":{"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?

| Selection                       | Input                                                             |
| ------------------------------- | ----------------------------------------------------------------- |
| Creator location                | `blogger.location`, an array of strings                           |
| Audience location               | `fans.location`, not the creator's location                       |
| Creator note-keyword search     | `keyword` with `search_type: 1`, the default                      |
| Nickname search                 | `keyword` with `search_type: 0`                                   |
| Image-note / video quoted price | min/max under `coop.pic_price` / `coop.video_price`               |
| Recent cooperation industry     | `coop.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](/guides/xiaohongshu-creator-shortlist) · [Find similar creators](/faq/xiaohongshu-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:

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

```bash
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](/guides/xiaohongshu-creator-shortlist). Run the guide's complete `pgy_candidates.py` locally:

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