# 小红书 API | Xiaohongshu (XHS / RedNote) Pro Scraper (`selleraim.com/xiaohongshu-pro-scraper`) Actor

小红书 / Xiaohongshu / XHS / RedNote data API. Seven modes: keyword search, note details, comments, creator profile, topic feed, hot list, keyword suggestions. Returns likes, collects, comments, hashtags, images, location, time. No cookies or login. For SEO, market research, KOL discovery, AI datasets.

- **URL**: https://apify.com/selleraim.com/xiaohongshu-pro-scraper.md
- **Developed by:** [Seller Aim](https://apify.com/selleraim.com) (community)
- **Categories:** Social media, Developer tools, AI
- **Stats:** 535 total users, 98 monthly users, 98.9% runs succeeded, 4 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $5.00 / 1,000 search / list results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## 小红书 API | Xiaohongshu (XHS / RedNote) Pro Scraper

Full-featured **小红书 / Xiaohongshu / XHS / RedNote** data API. **Seven modes, one Actor**, clean structured JSON. No login, no cookies, no broken-token surprises.

Built for serious workloads — market research teams pulling daily competitive intelligence, AI training pipelines harvesting Chinese-language UGC, KOL discovery tools, brand-watch dashboards.

### 中文说明

小红书数据 API,一个 Actor 覆盖 **七种模式**:关键词搜索、笔记详情、博主主页与作品、话题(标签)信息流、创作灵感榜、关键词联想、公开热门流。

- **无需 cookie、无需登录**,不会因为 token 过期而中断。
- 返回扁平化 JSON:标题、正文、作者、点赞、收藏、评论数、话题标签、图集、视频地址、发布时间、IP 归属地。
- 支持导出 JSON / CSV / Excel / HTML / XML,也可通过 Apify REST API 接入 n8n、Make、Zapier 或自建流水线。
- 适用场景:选品与市场调研、品牌舆情监控、KOL 达人挖掘、SEO 关键词研究、AI 训练语料采集。

计费:列表类结果 **$5.00 / 1,000 条**,笔记详情 **$20.00 / 1,000 条**,平台计算费用已包含(不额外收取)。详见下方 Pricing。

### Support / 联系我们

Bug、字段缺失、需要新的模式或更高并发?请在 Actor 页面的 **Issues** 标签提交,我们通常在 24–72 小时内响应。需要定制端点、专用代理或 SLA,可通过 Apify 站内聊天联系。

### What does this Actor do?

Pick a mode, give it inputs, get a dataset:

- **Keyword search** (`search`) — search Xiaohongshu by keyword with full sort and filter options (newest, most liked, video-only, last 24h, etc.)
- **Note details** (`notes`) — paste a note URL or an `xhslink.com` share link, get the full body, all images, hashtags, engagement counts, location, and optional comments.
- **User profile + posts** (`user`) — fetch a creator's profile (followers, IP location, bio) plus their recent posts in one run.
- **Topic / hashtag feed** (`topic`) — pull every recent note tagged with a topic.
- **Creator inspiration feed** (`inspiration`) — Xiaohongshu's creator-centre board of trending topics, each with a heat score and a deep link.
  (The old `hotsearch` 热榜 mode is **retired** — Xiaohongshu withdrew that endpoint upstream with no replacement. Runs using it now fail fast with an explanation instead of returning an empty dataset, and are not charged.)
- **Keyword suggestions** (`suggest`) — seed a keyword, get Xiaohongshu's autocomplete suggestions. Built for SEO and content research.
- **Public trending feed** (`trending`) — the anonymous "Hot Notes" homepage strip, no Xiaohongshu account needed.

Each note returns a flat, schema-validated JSON row that's downloadable as JSON, CSV, Excel, HTML, or XML — and queryable via the Apify REST API for pipeline integration.

### Why use Xiaohongshu Pro Scraper?

- **No cookies, no breakage.** Many Xiaohongshu actors rely on the customer's logged-in cookie, which expires every few days — customers end up with a stream of 401s. We use a maintained mobile-app surface that stays stable.
- **Seven modes in one Actor.** Search, note detail, user, topic, inspiration feed, keyword suggestions, trending — pick a mode per run; no juggling separate Actors.
- **Topic feeds and keyword research included.** Hashtag-level feeds and Xiaohongshu autocomplete are rarely available elsewhere in the Store.
- **Full-field output.** Title, body text, author, likes, collects, comment count, hashtags, image gallery, video URL, publish time, geo / IP location — all in one row.
- **AI training-ready.** Chinese-language UGC, clean JSON, deduplicable by `noteId`. Drop straight into a vector DB, an LLM fine-tune set, or a trend classifier.
- **Honest per-type pricing.** Cheap list results and expensive full-detail results are billed separately, so a 1,000-note keyword sweep costs $5 — not $20.

### How to use

1. Open the Actor and click **Try for free**.
2. In the Input tab, pick a **Scrape mode** (search is the default).
3. Fill the inputs for your mode:
   - **search**: keywords, optional sort/filter
   - **notes**: full note URLs or `xhslink.com` share links
   - **user**: user IDs
   - **topic**: topic names (without `#`)
   - **suggest**: seed keywords
   - **inspiration** / **trending**: nothing required
4. Set **Max items per input** (default 30).
5. Click **Save & Start**. Results stream into the dataset live.
6. Download or stream the dataset; schedule the run under the **Schedules** tab.

### Input

| Field | Type | Used in mode | Description |
|---|---|---|---|
| `mode` | string | all | One of `search`, `notes`, `user`, `topic`, `inspiration`, `suggest`, `trending`. (`hotsearch` is retired.) |
| `keywords` | array | search | Keywords to search. |
| `noteUrls` | array | notes | Note URLs or `xhslink.com` share links to fetch details for. |
| `userIds` | array | user | User IDs to fetch profiles and posts for. |
| `topicNames` | array | topic | Topic / hashtag names (without `#`). |
| `suggestKeywords` | array | suggest | Seed keywords for autocomplete suggestions. |
| `maxItemsPerInput` | integer (1–500) | all | Cap per input. Default 30. |
| `sortType` | enum | search | `general` / `time_descending` / `popularity_descending` / `comment_descending` / `collect_descending`. |
| `noteType` | enum | search | `不限` / `视频笔记` / `普通笔记` / `直播笔记`. |
| `timeFilter` | enum | search | `不限` / `一天内` / `一周内` / `半年内`. |
| `fetchComments` | boolean | notes, search | Also fetch up to 20 top comments per note. Adds run time. |
| `proxyConfiguration` | object | trending only | Only used for the trending fallback. |

JSON example — keyword search:

```json
{
    "mode": "search",
    "keywords": ["AI编程", "护肤"],
    "maxItemsPerInput": 100,
    "sortType": "popularity_descending",
    "timeFilter": "一周内",
    "fetchComments": false
}
```

### Output

```json
{
    "noteId": "69fba039000000003803426d",
    "title": "Claude Code 零基础终极教程！",
    "bodyText": "这是你能看到的最完整的Claude Code 零基础系统教程。 🔹 从安装到接入第三方模型 🔹 讲透 Hooks、S…",
    "author": "木子不写代码",
    "authorId": "5e2a3c1d000000000100abc7",
    "likes": 117895,
    "collects": 172097,
    "commentsCount": 4521,
    "isVideo": true,
    "imageUrls": [
        "https://sns-webpic-qc.xhscdn.com/.../1.jpg"
    ],
    "videoUrl": "https://sns-video-bd.xhscdn.com/.../master.mp4",
    "hashtags": ["#ClaudeCode", "#AI编程", "#提示词"],
    "publishedAt": "2026-04-13T09:42:00.000Z",
    "location": "上海",
    "comments": [
        { "author": "用户A", "text": "太实用！", "likes": 42 }
    ],
    "noteUrl": "https://www.xiaohongshu.com/explore/69fba039000000003803426d",
    "keyword": "AI编程",
    "scrapedAt": "2026-05-22T09:26:33.733Z"
}
```

You can download the dataset in various formats such as JSON, HTML, CSV, or Excel.

#### Output fields

| Field | Description |
|---|---|
| `noteId` | Xiaohongshu's internal note ID. |
| `title` | Note title. |
| `bodyText` | Full note body text. |
| `author` | Display name of the author. |
| `authorId` | Internal user ID — pair with `mode: "user"` to drill into the author. |
| `likes` | Like count. |
| `collects` | Collect (favourite) count. |
| `commentsCount` | Total comment count. |
| `isVideo` | True if Xiaohongshu marks the note as a video. |
| `imageUrls` | All images in the note. |
| `videoUrl` | Video src for video notes. |
| `hashtags` | Hashtags / topics referenced. |
| `publishedAt` | ISO 8601 publish time. |
| `location` | Author IP location (city / region). |
| `comments` | Up to 20 top comments when `fetchComments` is on. |
| `noteUrl` | Public deep link. |
| `keyword` | Search keyword that surfaced this note (search mode only). |
| `topic` | Topic name (topic mode only). |
| `userId` | Author ID (user mode only). |
| `scrapedAt` | ISO 8601 timestamp of scrape. |

### How much does it cost to scrape Xiaohongshu?

This Actor uses **pay-per-event** pricing, billed by result type:

| Event | Price | Modes |
|---|---|---|
| **Search / list result** | **$5.00 / 1,000** ($0.005 each) | `search`, `topic`, `user`, `inspiration`, `suggest`, `trending` |
| **Full note detail** | **$20.00 / 1,000** ($0.02 each) | `notes` |

List results are cheap because they are cheap for us to produce. Full note details hit a far more expensive upstream endpoint, so they are priced separately instead of averaging that cost into every row — which is why a 1,000-note keyword sweep costs **$5, not $20**.

**Platform usage is included.** You are not billed separately for compute or proxies.

#### Free vs. paid Apify plans

Apify free-plan users get **2 sample runs capped at 10 results each** so you can verify the data shape and quality before committing. Further runs from free accounts are blocked with an upgrade prompt — this Actor relies on a paid backend, so we can't subsidise unlimited free use. Any Apify paid plan (see [Apify pricing](https://apify.com/pricing)) unlocks unlimited runs at the rates above.

#### Cost estimates

| Goal | Items / run | Mode | Est. cost / run |
|---|---|---|---|
| Quick scan of one keyword | 50 | `search` | ~$0.25 |
| Keyword research sweep | 200 suggestions | `suggest` | ~$1.00 |
| Hashtag round-up | 500 | `topic` | ~$2.50 |
| Daily brand monitoring | 1,000 | `search` | ~$5.00 / day |
| KOL deep dive (full details) | 200 notes | `notes` | ~$4.00 |

#### How to keep costs down

Use `search`, `topic`, or `user` mode whenever you can — they already return title, body, likes, collects, comment count, hashtags, and images at the list rate. Only reach for `notes` mode when you specifically need one note's complete detail record.

### Tips

- **Schedule, don't poll.** Xiaohongshu rotates trending content every few hours; scheduling daily / 6-hourly delivers the right cadence vs cost.
- **Deduplicate by `noteId`.** Sequential runs overlap; merge and dedupe on the `noteId` field.
- **Use `suggest` before `search`.** Mine the autocomplete list first, then search only the terms that matter.
- **Pair user + notes modes.** Use `mode: "user"` to find prolific authors, then drill into a specific top note with `mode: "notes"`.
- **Pair `popularity_descending` with `timeFilter: "一周内"`** to surface this week's breakout posts.
- **Don't enable `fetchComments` unless you need them.** Each comment-bearing note takes an extra request and adds run time.

### FAQ

**Q: Why is this Actor different from the other Xiaohongshu scrapers on the Store?**
A: Most existing actors depend on the customer providing a logged-in Xiaohongshu cookie that expires every few days. We don't. We've engineered around the public mobile-app surface so the Actor stays stable across cookie expiries — and we bill list results separately from full details so you don't overpay for bulk keyword work.

**Q: Will this break when Xiaohongshu changes their API?**
A: Possibly. Our team maintains the backend; we patch usually within 24-72 hours of a backend change. Bug reports via the Issues tab.

**Q: Is scraping Xiaohongshu legal?**
A: We pull only publicly-accessible content — what any visitor can see without an account. Your usage is your responsibility; comply with your jurisdiction's law and Xiaohongshu's Terms of Service. Do not scrape private profiles or use the data to identify individuals.

**Q: Can I get my data via API?**
A: Yes. Every Apify run exposes a stable [REST API](https://docs.apify.com/api/v2) for inputs, datasets, and run status. Plug into n8n, Make, Zapier, or your own pipeline.

**Q: Is there a free tier?**
A: Apify gives new accounts free platform credit, and this Actor allows **2 sample runs of up to 10 results each** on free plans so you can evaluate the output before paying.

**Q: How fast are runs?**
A: Search mode: ~5 seconds per page (≈20 notes). User mode: ~3 seconds per page. Note-detail mode: 1-2 seconds per note. Topic mode: ~4 seconds per page.

**Q: I need a richer integration or higher-volume contract.**
A: Reach out via Apify chat. Custom endpoints, dedicated proxies, and SLAs available on request.

# Actor input Schema

## `mode` (type: `string`):

What kind of data to pull from Xiaohongshu / RedNote. NOTE: "hotsearch" (热榜) is RETIRED — Xiaohongshu withdrew that endpoint with no replacement. Use "inspiration" for trending creator topics instead.

## `keywords` (type: `array`):

Keywords to search for in Xiaohongshu. Used when mode is 'search'.

## `noteUrls` (type: `array`):

Xiaohongshu note URLs to fetch full details for. Used when mode is 'notes'. Accepts three formats: (1) standard web URL https://www.xiaohongshu.com/explore/<noteId>, (2) /discovery/item/<noteId>, or (3) xhslink.com share-link from the XHS app share sheet (e.g. https://xhslink.com/a/EZ4M9TwMA6c3 — auto-resolved to the underlying note).

## `userIds` (type: `array`):

Xiaohongshu user IDs to fetch profiles + recent posts for. Used when mode is 'user'. Find a user ID in the profile URL (/user/profile/<userId>).

## `topicNames` (type: `array`):

Xiaohongshu topic URLs (e.g. https://www.xiaohongshu.com/page/topics/5c1cc866febed9000184b7c1) or raw page\_id strings (24-char hex). Used when mode is 'topic'. Free-form Chinese topic names are no longer supported by the upstream feed — please use the URL or page\_id.

## `suggestKeywords` (type: `array`):

Seed keywords to fetch search-box suggestions for. Used when mode is 'suggest'. Each seed returns up to ~10 related search phrases — great for SEO and content-discovery research.

## `maxItemsPerInput` (type: `integer`):

Cap per keyword / URL / user / topic. Each item returned is one billed result.

## `sortType` (type: `string`):

Sort order for keyword search.

## `noteType` (type: `string`):

Filter by note type.

## `timeFilter` (type: `string`):

Filter by recency.

## `fetchComments` (type: `boolean`):

When on, fetches up to 20 top comments per note. Significantly increases run time and is billed per comment-bearing note.

## `proxyConfiguration` (type: `object`):

Only used in the 'trending' fallback mode. The other modes do not need proxies.

## Actor input object example

```json
{
  "mode": "search",
  "keywords": [
    "AI"
  ],
  "noteUrls": [],
  "userIds": [],
  "topicNames": [],
  "suggestKeywords": [],
  "maxItemsPerInput": 30,
  "sortType": "general",
  "noteType": "不限",
  "timeFilter": "不限",
  "fetchComments": false,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "keywords": [
        "AI"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("selleraim.com/xiaohongshu-pro-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "keywords": ["AI"] }

# Run the Actor and wait for it to finish
run = client.actor("selleraim.com/xiaohongshu-pro-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "keywords": [
    "AI"
  ]
}' |
apify call selleraim.com/xiaohongshu-pro-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,selleraim.com/xiaohongshu-pro-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/AmMXqcY96Hf0o9fKd/builds/zatDi5JeYJVY09SZR/openapi.json