# Xiaohongshu PGY creator notes API

> A page of a creator’s notes as PGY shows them (笔记案例), by PGY creator ID: reads, likes, saves, shop visitors, whether it was sponsored and for which brand. Sponsored or cross-domain sponsored notes alone, image or video notes alone, newest, most read or most engaged first, by content feature or category, with reads of organic traffic alone if wanted.

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

- **Endpoint**: `GET /v1/xiaohongshu/pgy/creators/notes/list`
- **ID**: `xiaohongshu.pgy.creators.notes.list`
- **Price**: $0.04 per call · about 8 notes per page
- **Returns**: a page of about 8 notes (`data.items`, PgyCreatorPost objects)
- **Status**: preview
- **Good for**: Creator discovery, Competitor monitoring

## Price

One call costs $0.04 and returns one page of about 8 notes. Collecting 1,000 notes takes about 125 calls, $5.00 in total. Each page is a separate call; failed calls are not charged.

## Parameters

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `id` | string | yes |  | PGY creator ID (24 hex characters, the same as the Xiaohongshu user ID), from the PGY creator search. (e.g. `591662306a6a6967b63e7f16`) |
| `tab` | string: all / sponsored / cross_domain | no | `all` | Which notes: all (the default), sponsored notes alone, or cross-domain sponsored notes alone (those with shop visitors). |
| `type` | string: image / video | no |  | Image notes or video notes alone; both when left out. Only with tab=all. |
| `sort` | string: latest / most_read / most_engaged | no | `latest` | Order: newest first (the default), most read first or most interactions first. |
| `traffic` | string: all / organic | no | `all` | Which traffic the reads count: all, promoted traffic included (the default), or organic traffic alone. Likes and saves stay the same. |
| `feature_tag` | string | no |  | Only notes with this content feature tag, as written in the creator detail’s ext.feature_tags. A tag that does not exist finds nothing. (e.g. `vlog`) |
| `category` | string | no |  | Only notes of this content category, as written in the creator detail’s categories. A category that does not exist finds nothing. (e.g. `出行旅游`) |
| `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 |  | Fields to keep, by path (author.name), to save tokens. In a query string: comma-separated. |

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

## Returned fields

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

| Field | Type | Description |
|---|---|---|
| `id` | string | Note ID. |
| `title` | string \| null | The note's title. |
| `type` | string \| null | Image note or video note. |
| `published_at` | string \| null | Publication day, as 00:00 China time (the platform gives the day only). |
| `cover_url` | string \| null | Cover image. |
| `is_sponsored` | boolean \| null | Whether it was made for a brand (see brand). |
| `brand` | string \| null | The brand it was made for, in the platform's words; null when not sponsored. |
| `is_promoted` | boolean \| null | Whether paid promotion sent traffic to it (含推广流量); not the same as sponsored. |
| `metrics` | PgyPostMetrics | The note's figures. |
| `ext` | object | Platform-specific extras. Only returned with view=full. |

## Request examples

### cURL

```bash
curl -G "https://api.okdata.online/v1/xiaohongshu/pgy/creators/notes/list" \
  -H "Authorization: Bearer $OKDATA_API_KEY" \
  --data-urlencode 'id=591662306a6a6967b63e7f16'
```

### Python

```python
import os
import requests

resp = requests.get(
    "https://api.okdata.online/v1/xiaohongshu/pgy/creators/notes/list",
    headers={"Authorization": f"Bearer {os.environ['OKDATA_API_KEY']}"},
    params={"id": "591662306a6a6967b63e7f16"},
    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)
print("cost: $" + body["meta"]["billing"]["amount"])
```

### TypeScript

```ts
const url = new URL('https://api.okdata.online/v1/xiaohongshu/pgy/creators/notes/list');
url.searchParams.set('id', "591662306a6a6967b63e7f16");

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);
}
console.log('cost: $' + body.meta.billing.amount);
```

### MCP

```json
{
  "name": "call",
  "arguments": {
    "capability": "xiaohongshu.pgy.creators.notes.list",
    "id": "591662306a6a6967b63e7f16"
  }
}
```

Or ask an agent that has the MCP server connected:

> Use Xiaohongshu PGY creator notes and sum up what comes back.

## Response example

```json
{
  "code": "ok",
  "request_id": "0f6c2a8e-4b1d-4e0a-9a51-3c7d2b9e1f20",
  "data": {
    "items": [
      {
        "id": null,
        "title": null,
        "type": null,
        "published_at": null,
        "cover_url": null,
        "is_sponsored": null,
        "brand": null,
        "is_promoted": null,
        "metrics": {
          "views": null,
          "likes": null,
          "favorites": null,
          "shop_visits": null
        }
      }
    ]
  },
  "page": {
    "next_cursor": "eyJvIjoyMH0",
    "has_more": true
  },
  "warnings": [],
  "meta": {
    "capability": "xiaohongshu.pgy.creators.notes.list",
    "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: code, request_id, message and message_zh (a fixed sentence per code), charged, retry, retry_after_seconds, param and docs_url, with the specifics in problems. They are not charged; only settlement_unknown is unknown until looked up. The full table: https://okdata.online/docs/errors/

## Questions

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

One call costs $0.04 and returns one page of about 8 notes. Collecting 1,000 notes takes about 125 calls, $5.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 search](https://okdata.online/apis/xiaohongshu/pgy/creators/search/): $0.04 per call · about 20 creators 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
- [Xiaohongshu image search](https://okdata.online/apis/xiaohongshu/images/search/): $0.02 per call · about 20 posts per page
- [Xiaohongshu comment replies](https://okdata.online/apis/xiaohongshu/comments/replies/list/): $0.02 per call · about 5 comments per page
- [Xiaohongshu topic notes](https://okdata.online/apis/xiaohongshu/topics/notes/list/): $0.02 per call · about 10 notes per page
- [Xiaohongshu topic detail](https://okdata.online/apis/xiaohongshu/topics/get/): $0.02 per call
- [Xiaohongshu account search](https://okdata.online/apis/xiaohongshu/users/search/): $0.02 per call · about 20 accounts per page
- [Xiaohongshu shop product detail](https://okdata.online/apis/xiaohongshu/shop/products/get/): $0.02 per call
- [Xiaohongshu search suggestions](https://okdata.online/apis/xiaohongshu/keywords/related/): $0.02 per call · about 10 results per page
- [Xiaohongshu video note with its video](https://okdata.online/apis/xiaohongshu/videos/get/): $0.02 per call
- [Xiaohongshu PGY keyword search index](https://okdata.online/apis/xiaohongshu/pgy/keywords/history/): $0.04 per call
- [Xiaohongshu PGY related keywords](https://okdata.online/apis/xiaohongshu/pgy/keywords/related/): $0.04 per call · about 98 results per page
- [Xiaohongshu PGY creator audience](https://okdata.online/apis/xiaohongshu/pgy/creators/audience/get/): $0.04 per call
- [Xiaohongshu PGY creator note metrics](https://okdata.online/apis/xiaohongshu/pgy/creators/metrics/): $0.04 per call
- [Xiaohongshu PGY creator follower history](https://okdata.online/apis/xiaohongshu/pgy/creators/followers/history/): $0.04 per call
- [Xiaohongshu PGY similar creators](https://okdata.online/apis/xiaohongshu/pgy/creators/related/): $0.04 per call · about 4 creators per page
- [Xiaohongshu PGY trending notes](https://okdata.online/apis/xiaohongshu/pgy/notes/trending/): $0.04 per call · about 34 notes per page
- [Xiaohongshu PGY creator costs and summary](https://okdata.online/apis/xiaohongshu/pgy/creators/costs/metrics/): $0.04 per call
- [Xiaohongshu PGY creator follower quality](https://okdata.online/apis/xiaohongshu/pgy/creators/followers/metrics/): $0.04 per call
- [Xiaohongshu PGY creator core figures history](https://okdata.online/apis/xiaohongshu/pgy/creators/costs/history/): $0.04 per call
- [Xiaohongshu PGY note figures](https://okdata.online/apis/xiaohongshu/pgy/notes/get/): $0.04 per call

## At a glance

- **Short name**: Xiaohongshu PGY creator notes
- **Also called**: rednote sponsored notes, xhs creator brand deals
- **Category**: [Creators](https://okdata.online/categories/creator/)
- **Group**: [Xiaohongshu PGY API](https://okdata.online/apis/xiaohongshu/pgy/)
- **Data type**: Creator posts API
- **Status**: preview. It may still change; any change is announced beforehand.
- **Price**: $0.04 per call · failed calls are free
- **Returns**: About 8 notes a page, with a cursor for the next page
- **If a call fails**: Not charged. When a data source fails, the next one is tried; errors and timeouts cost nothing.

## When it is charged

- Data comes back: $0.04 per call
- Bad parameters, errors, timeouts: Free

| When | Charge |
|---|---|
| Each further page | A new call: $0.04 |
| Most one call costs | $0.04 |
| An empty answer | $0.04 |
| Not found (the platform has no such item) | Free |
| Bad parameters, errors, timeouts | Free |
| A retry with the same Idempotency-Key within 24 hours | Charged once |

A failed call is free; an empty answer costs $0.04; not found is free.

Prices from price book 1b273c48fea9634e. [Every price on this platform](https://okdata.online/pricing/xiaohongshu/)

- New accounts get $0.10 of credit, no card needed: 2 calls to this endpoint.
- About 125 calls fetch 1,000 notes: $5.00 in all.

## Known limits

- About 8 notes come back per page; the platform sets the page size, so there is no page-size parameter.
- For the next page, pass `page.next_cursor` back as `cursor`. A cursor stays valid for 24 hours. When `page.has_more` is false there is nothing left.

## Fields by view

The view column is the smallest `view` a field comes back in: `compact` returns only compact fields, `standard` adds the standard ones, `full` returns everything. The default is `standard`.

- `compact`: `id`, `title`, `type`, `published_at`, `is_sponsored`, `brand`, `is_promoted`, `metrics`
- `standard`: `cover_url`
- `full`: `ext`

## Common errors on this endpoint

| HTTP | Code | Meaning | Charged | Retry |
|---|---|---|---|---|
| 400 | `invalid_params` | A parameter is missing, has the wrong type or value, or the method is wrong. problems lists each one; param names the first. | no | after a fix |
| 400 | `cursor_mismatch` | The cursor was sent to another endpoint, or with other parameters than the page it came from (view and fields may change). | no | after a fix |
| 401 | `unauthorized` | The key is missing, malformed, revoked, disabled or expired (reason says which when known). | no | no |
| 402 | `insufficient_balance` | The balance (available) cannot cover the most this call could cost (required). | no | after a fix |
| 404 | `not_found` | The post, account or page does not exist or is not public. Endpoints whose charge_when_not_found is above 0 charge this answer (the source billed us for it): the body then says charged: true and amount. | no | no |
| 410 | `cursor_expired` | The cursor is older than the endpoint's cursor lifetime (page.cursor_expires_at said when). | no | no |
| 429 | `rate_limited` | The account sent too many requests this minute (reason: rate) or has too many calls running (reason: concurrency). | no | yes |
| 500 | `settlement_unknown` | The data came back, but the charge could not be confirmed. | unknown until looked up | with the same Idempotency-Key |
| 502 | `upstream_failed` | Every data source for this endpoint failed on this request. | no | yes |
| 503 | `capability_paused` | This endpoint is paused right now; nothing ran. | no | yes |
| 504 | `timeout` | The data did not come back in time. The hold was released, so nothing was charged. | no | yes |

[All error codes](https://okdata.online/docs/errors/)

## Use it in your AI

> Read https://okdata.online/apis/xiaohongshu/pgy/creators/notes/list.md, then call this endpoint for me through okdata; my key is in the OKDATA_API_KEY environment variable. Use Xiaohongshu PGY creator notes and sum up what comes back.

## Xiaohongshu (RedNote) endpoints by group

- [Xiaohongshu PGY API](https://okdata.online/apis/xiaohongshu/pgy/): Xiaohongshu PGY creator search $0.04, Xiaohongshu PGY creator detail $0.04, Xiaohongshu PGY keyword search index $0.04, Xiaohongshu PGY related keywords $0.04, Xiaohongshu PGY creator audience $0.04, Xiaohongshu PGY creator note metrics $0.04, Xiaohongshu PGY creator follower history $0.04, Xiaohongshu PGY similar creators $0.04, Xiaohongshu PGY trending notes $0.04, Xiaohongshu PGY creator costs and summary $0.04, Xiaohongshu PGY creator follower quality $0.04, Xiaohongshu PGY creator core figures history $0.04, Xiaohongshu PGY note figures $0.04
- [Xiaohongshu Shop API](https://okdata.online/apis/xiaohongshu/shop/): Xiaohongshu shop product search $0.02, Xiaohongshu shop product reviews $0.02, Xiaohongshu shop product detail $0.02