# Xiaohongshu PGY keyword search index API

> A keyword’s search index on Xiaohongshu day by day over about the last three months (the platform sets the period), with each day’s notes about it and how often they were shown, read and engaged with. The index is the platform’s measure, not a count of searches.

Canonical page: https://okdata.online/apis/xiaohongshu/pgy/keywords/history/

- **Endpoint**: `GET /v1/xiaohongshu/pgy/keywords/history`
- **ID**: `xiaohongshu.pgy.keywords.history`
- **Price**: $0.04 per call
- **Returns**: one KeywordHistory object (`data.item`)
- **Status**: preview
- **Good for**: Trend research, Content research

## Price

One call costs $0.04 and returns one keyword_history. 1,000 lookups cost $40.00. Failed calls are not charged.

## Parameters

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `keyword` | string | yes |  | One keyword. (e.g. `面膜`) |
| `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 [KeywordHistory](https://okdata.online/docs/objects/keyword_history/).

| Field | Type | Description |
|---|---|---|
| `keyword` | string | The keyword. |
| `points` | KeywordPoint[] | One entry a day, oldest first. |
| `ext` | object | Platform-specific extras. Only returned with view=full. |

## Request examples

### cURL

```bash
curl -G "https://api.okdata.online/v1/xiaohongshu/pgy/keywords/history" \
  -H "Authorization: Bearer $OKDATA_API_KEY" \
  --data-urlencode 'keyword=面膜'
```

### Python

```python
import os
import requests

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

row = body["data"]["item"]
print(row)
print("cost: $" + body["meta"]["billing"]["amount"])
```

### TypeScript

```ts
const url = new URL('https://api.okdata.online/v1/xiaohongshu/pgy/keywords/history');
url.searchParams.set('keyword', "面膜");

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}`);

const row = body.data.item;
console.log(row);
console.log('cost: $' + body.meta.billing.amount);
```

### MCP

```json
{
  "name": "call",
  "arguments": {
    "capability": "xiaohongshu.pgy.keywords.history",
    "keyword": "面膜"
  }
}
```

Or ask an agent that has the MCP server connected:

> Use Xiaohongshu PGY keyword search index and sum up what comes back.

## Response example

```json
{
  "code": "ok",
  "request_id": "0f6c2a8e-4b1d-4e0a-9a51-3c7d2b9e1f20",
  "data": {
    "item": {
      "keyword": null,
      "points": [
        {
          "date": null,
          "search_index": null,
          "composite_index": null,
          "notes": null,
          "impressions": null,
          "views": null,
          "engagements": null
        }
      ]
    }
  },
  "warnings": [],
  "meta": {
    "capability": "xiaohongshu.pgy.keywords.history",
    "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 keyword search index API cost?

One call costs $0.04 and returns one keyword_history. 1,000 lookups cost $40.00. Failed calls are not charged.

### 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 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 notes](https://okdata.online/apis/xiaohongshu/pgy/creators/notes/list/): $0.04 per call · about 8 notes per page
- [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 keyword search index
- **Also called**: rednote keyword trend, xhs search index
- **Category**: [Social media](https://okdata.online/categories/social/)
- **Group**: [Xiaohongshu PGY API](https://okdata.online/apis/xiaohongshu/pgy/)
- **Status**: preview. It may still change; any change is announced beforehand.
- **Price**: $0.04 per call · failed calls are free
- **Returns**: One KeywordHistory, as data.item
- **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 |
|---|---|
| Most one call costs | $0.04 |
| An empty answer | Free |
| 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 is free; 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.
- 1,000 lookups cost $40.00.

## 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`: `keyword`, `points`
- `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 |
| 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 |
| 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/keywords/history.md, then call this endpoint for me through okdata; my key is in the OKDATA_API_KEY environment variable. Use Xiaohongshu PGY keyword search index 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 related keywords $0.04, Xiaohongshu PGY creator audience $0.04, Xiaohongshu PGY creator note metrics $0.04, Xiaohongshu PGY creator notes $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