# Xiaohongshu PGY creator search API

> Find Xiaohongshu creators on PGY (蒲公英), the official creator marketplace, by what their notes are about or by name, filtered by followers and note type, sorted by followers, engagement, reads or rate. Each with followers, median reads and engagements of everyday notes, content categories and what an image note and a video note cost (in yuan).

Canonical page: https://okdata.online/apis/xiaohongshu/pgy/creators/search/

- **Endpoint**: `GET /v1/xiaohongshu/pgy/creators/search`
- **ID**: `xiaohongshu.pgy.creators.search`
- **Price**: $0.04 per call · about 20 creators per page
- **Returns**: a page of about 20 creators (`data.items`, Creator objects)
- **Status**: beta
- **Good for**: Creator discovery

## Price

One call costs $0.04 and returns one page of about 20 creators. Collecting 1,000 creators takes about 50 calls, $2.00 in total. Each page is a separate call; failed calls are not charged.

## Parameters

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `query` | string | yes |  | Keywords, as a person would type them into the platform search box. (e.g. `户外`) |
| `search_by` | string: notes / name | no | `notes` | Match the words against what creators post (the default) or against their names. |
| `followers_min` | integer | no |  | At least this many followers. (e.g. `100000`) |
| `followers_max` | integer | no |  | At most this many followers. (e.g. `500000`) |
| `type` | string: all / image / video | no | `all` | Creators who mostly post image notes or video notes; both by default. |
| `sort` | string: relevance / most_followers / most_engagements / most_reads / lowest_rate / highest_rate | no | `relevance` | Result order. |
| `cursor` | string | no |  | Opaque cursor from page.next_cursor of the previous call. Each page is a separate call. |
| `view` | string: compact / standard / full | no | `standard` | How much of each object comes back. full adds platform-specific fields under ext. |
| `fields` | string | no |  | Comma-separated fields to keep, to save tokens. |

cursor, view and fields work as described in [Requests](https://okdata.online/docs/requests/).

## Returned fields

Each item is a [Creator](https://okdata.online/docs/objects/creator/).

| Field | Type | Description |
|---|---|---|
| `id` | string | The marketplace's creator ID; the other marketplace endpoints take it. |
| `url` | string | The creator's page on the marketplace. |
| `account_id` | string \| null | The creator's own account ID on the platform, where the marketplace gives it. |
| `username` | string \| null | Handle on the platform, where given. |
| `name` | string | Display name. |
| `avatar_url` | string \| null | Avatar image URL. |
| `location` | string \| null | Where the creator says they are. |
| `gender` | string \| null | The creator's gender as the marketplace lists it. |
| `followers` | integer \| null | Followers. |
| `categories` | string[] \| null | Content categories in the marketplace’s own words. |
| `engagement_rate` | number \| null | Interactions per view of recent posts, 0 to 1 (0.038 is 3.8%). |
| `median_views` | integer \| null | Median views or reads of recent everyday posts. |
| `median_engagements` | integer \| null | Median interactions (likes, comments, saves, shares) of recent everyday posts. |
| `rates` | Rate[] \| null | Published rates for sponsored work; null when the marketplace hides them. |
| `ext` | object | Platform-specific extras. Only returned with view=full. |

## Request examples

### cURL

```bash
curl -G "https://api.okdata.online/v1/xiaohongshu/pgy/creators/search" \
  -H "Authorization: Bearer $OKDATA_API_KEY" \
  --data-urlencode 'query=户外'
```

### Python

```python
import os
import requests

resp = requests.get(
    "https://api.okdata.online/v1/xiaohongshu/pgy/creators/search",
    headers={"Authorization": f"Bearer {os.environ['OKDATA_API_KEY']}"},
    params={"query": "户外"},
    timeout=60,
)
body = resp.json()
if body["code"] != "ok":
    raise RuntimeError(f"{body['code']}: {body['message']} (charged: {body['charged']})")

for row in body["data"]["items"]:
    print(row["name"], row["followers"], row["engagement_rate"])
print("cost: $" + body["meta"]["billing"]["amount"])
```

### TypeScript

```ts
const url = new URL('https://api.okdata.online/v1/xiaohongshu/pgy/creators/search');
url.searchParams.set('query', "户外");

const res = await fetch(url, {
  headers: {
    Authorization: `Bearer ${process.env.OKDATA_API_KEY}`,
  },
});
const body = await res.json();
if (body.code !== 'ok') throw new Error(`${body.code}: ${body.message}`);

for (const row of body.data.items) {
  console.log(row.name, row.followers, row.engagement_rate);
}
console.log('cost: $' + body.meta.billing.amount);
```

### MCP

```json
{
  "name": "call",
  "arguments": {
    "endpoint": "xiaohongshu.pgy.creators.search",
    "params": {
      "query": "户外"
    }
  }
}
```

Or ask an agent that has the MCP server connected:

> Use Xiaohongshu PGY creator search and shortlist ten creators with the best engagement for the money, with their rates.

## Response example

```json
{
  "code": "ok",
  "request_id": "0f6c2a8e-4b1d-4e0a-9a51-3c7d2b9e1f20",
  "data": {
    "items": [
      {
        "id": "5dfa1ee20000000001001cb3",
        "url": "https://pgy.xiaohongshu.com/solar/pre-trade/blogger-detail/5dfa1ee20000000001001cb3",
        "account_id": "5dfa1ee20000000001001cb3",
        "username": "shaka521",
        "name": "山野轻装",
        "avatar_url": "https://cdn.example.com/avatar/creator.jpg",
        "location": "江苏 苏州",
        "gender": "male",
        "followers": 176970,
        "categories": [
          "出行旅游",
          "旅行"
        ],
        "engagement_rate": null,
        "median_views": 198469,
        "median_engagements": 15935,
        "rates": [
          {
            "type": "image_note",
            "name": "图文笔记",
            "price": 16000,
            "currency": "CNY",
            "available": true,
            "settlement": null
          }
        ]
      }
    ]
  },
  "page": {
    "next_cursor": "eyJvIjoyMH0",
    "has_more": true
  },
  "warnings": [],
  "meta": {
    "capability": "xiaohongshu.pgy.creators.search",
    "billing": {
      "amount": "0.04",
      "currency": "USD",
      "balance_after": "9.96"
    },
    "unavailable": {},
    "cached": false,
    "replayed": false,
    "fetched_at": "2026-11-11T08:00:00Z"
  }
}
```

## Errors

Errors share one shape and are never charged, except a timeout, whose charge is unknown until looked up. The full table: https://okdata.online/docs/errors/

## Questions

### How much does the Xiaohongshu PGY creator search API cost?

One call costs $0.04 and returns one page of about 20 creators. Collecting 1,000 creators takes about 50 calls, $2.00 in total. Each page is a separate call; failed calls are not charged.

### How do I get the next page?

Pass page.next_cursor from the response back as the cursor parameter. When page.has_more is false there is nothing left. Every page is its own call at $0.04.

### Do I need a Xiaohongshu (RedNote) account, cookies or a QR login?

No. You send only your okdata API key. The data is public data from Xiaohongshu (RedNote); nothing is fetched with your own Xiaohongshu (RedNote) account.

### Am I charged when a call fails?

No. Every error response says charged: false, except a timeout, which says charged: null until the outcome is known. Resend with the same Idempotency-Key and you are never charged twice.

### What if Xiaohongshu (RedNote) does not show a field?

The field is null, and meta.unavailable names it with the reason: platform (the platform never shows it) or capability (we cannot fetch it yet).

## More Xiaohongshu (RedNote) endpoints

- [Xiaohongshu note search](https://okdata.online/apis/xiaohongshu/notes/search/): $0.02 per call · about 20 notes per page
- [Xiaohongshu note detail](https://okdata.online/apis/xiaohongshu/notes/get/): $0.02 per call
- [Xiaohongshu note comments](https://okdata.online/apis/xiaohongshu/notes/comments/list/): $0.02 per call · about 10 comments per page
- [Xiaohongshu account profile](https://okdata.online/apis/xiaohongshu/users/get/): $0.02 per call
- [Xiaohongshu account notes](https://okdata.online/apis/xiaohongshu/users/notes/list/): $0.02 per call · about 20 notes per page
- [Xiaohongshu hot topics](https://okdata.online/apis/xiaohongshu/trends/list/): $0.02 per call · about 20 board entries per page
- [Xiaohongshu PGY creator detail](https://okdata.online/apis/xiaohongshu/pgy/creators/get/): $0.04 per call
- [Xiaohongshu shop product search](https://okdata.online/apis/xiaohongshu/shop/products/search/): $0.02 per call · about 20 products per page
- [Xiaohongshu shop product reviews](https://okdata.online/apis/xiaohongshu/shop/products/reviews/list/): $0.02 per call · about 12 reviews per page

## Answers that use this endpoint

- [Can an AI agent shortlist Xiaohongshu or Douyin creators for a campaign?](https://okdata.online/answers/ai-agent-creator-shortlist/): Yes, if it has marketplace and content tools: the agent searches PGY (蒲公英) or Xingtu with your follower band, which returns each creator's rates in yuan and median reads or views, then reads their recent notes to judge fit and ranks them against your brief. A Xiaohongshu shortlist from 3 PGY searches, recent notes for 40 creators and full PGY profiles for 20 finalists costs about $1.72.
- [How do I shortlist creators by follower range and price on Douyin and Xiaohongshu?](https://okdata.online/answers/creator-shortlist-followers-price/): Search the two official creator marketplaces with a follower range: Xingtu for Douyin and PGY (蒲公英) for Xiaohongshu both return each creator's rates in yuan, so you drop everyone over budget and rank the rest by price per thousand median views. A page of 20 creators costs $0.004 on Xingtu and $0.04 on PGY; 200 candidates from each cost $0.44.
- [How do I find Xiaohongshu KOLs in a niche and get their follower counts?](https://okdata.online/answers/xiaohongshu-find-kol-creators/): Search PGY (蒲公英), Xiaohongshu's creator marketplace, by niche: each page lists 20 creators with followers, median reads and image and video note rates for $0.04. To catch creators who are not on PGY, search notes by keyword and look up the authors; 5 PGY pages, 5 note searches and 40 author profiles cost $1.10.
- [Is there an API for Xiaohongshu PGY (Pugongying) creator data and rates?](https://okdata.online/answers/xiaohongshu-pgy-creator-data-api/): Xiaohongshu does not publish a public API for browsing PGY creators; the official route is the PGY web console with a brand account. okdata reads the creator data PGY shows advertisers: one search returns 20 creators with image and video note rates for $0.04, and one creator's full PGY profile costs $0.04.