# RedNote (Xiaohongshu) Note Detail Scraper · 小红书笔记详情采集 (`nexgendata/rednote-note-detail`) Actor

- **URL**: https://apify.com/nexgendata/rednote-note-detail.md
- **Developed by:** [NexGenData](https://apify.com/nexgendata) (community)
- **Categories:** Social media, Automation
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $100.00 / 1,000 note details

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

## RedNote (Xiaohongshu) Note Detail Scraper · 小红书笔记详情采集

Turn any RedNote / Xiaohongshu (小红书) note URL or ID into a clean, structured data record — title, body, media, hashtags, author and full engagement metrics — in one call.

### ⚡ What you get

| Capability | Detail |
| --- | --- |
| Full note detail | Title, body text, note type (normal / video), media URLs |
| Engagement metrics | Likes, collects, comments and shares counts |
| Author data | Handle, user ID and profile URL |
| Media extraction | All image URLs and the video URL (for video notes) |
| Discovery & hashtags | Hashtag list, IP location and posted-at timestamp |
| Flexible input | Paste full share URLs (with `xsec_token`), bare IDs, or best-effort sample the live feed |
| Honest billing | **$0.10 per delivered note + $0.04 per actor start.** Blocked, not-found and unprocessed notes are never charged |

### 💰 Pricing

| Event | Price |
| --- | --- |
| Actor start | $0.04 per run |
| Note detail delivered (`note-detail`) | $0.10 per note |

Only genuine, id-verified notes that are pushed to the dataset are charged. A run that delivers nothing **fails** with a reason in the status message and charges only the start fee.

### 📏 Limits & time budget

- **Max 50 notes per run** (`noteUrls` and `maxItems` both cap at 50). Split larger lists across runs.
- The run keeps an internal **time budget**: it stops starting new notes 45 seconds before the run timeout so it can always finish cleanly. Notes it did not get to are listed in the status message as *not processed (time budget)* and are not charged. Each delivered note is charged and pushed incrementally, so a run that hits the budget still keeps every row it delivered.

### 🎯 Use cases

- **China social listening** — pull full post detail for any RedNote note your monitoring surfaces.
- **KOL / influencer research** — capture author handle, profile URL and per-post engagement for outreach lists.
- **Consumer & trend insight** — extract body text, hashtags and media to analyse what resonates with Chinese consumers.
- **Competitor content audits** — archive a competitor's notes with metrics to benchmark performance over time.
- **Dataset building for ML/NLP** — assemble structured Chinese-language post datasets with text, media and engagement signals.

### 🚀 How to use

**Apify Console** — open the actor, paste one or more note URLs into **Note URLs or IDs** (or set **Sample latest feed notes** to a number), then click **Start**. Results land in the run's dataset.

**Python (apify-client)**

```python
from apify_client import ApifyClient

client = ApifyClient("<YOUR_APIFY_TOKEN>")

run_input = {
    "noteUrls": [
        "https://www.xiaohongshu.com/explore/%3CNOTE_ID%3E?xsec_token=%3CTOKEN%3E"
    ],
    "proxyConfiguration": {"useApifyProxy": True, "apifyProxyGroups": ["RESIDENTIAL"]},
}

run = client.actor("nexgendata/rednote-note-detail").call(run_input=run_input)

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)
```

**cURL**

```bash
curl -X POST "https://api.apify.com/v2/acts/nexgendata~rednote-note-detail/runs?token=%3CYOUR_APIFY_TOKEN%3E" \
  -H "Content-Type: application/json" \
  -d '{
        "noteUrls": ["https://www.xiaohongshu.com/explore/%3CNOTE_ID%3E?xsec_token=%3CTOKEN%3E"],
        "proxyConfiguration": {"useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"]}
      }'
```

### 📊 Output fields

| Field | Description |
| --- | --- |
| `note_id` | Unique RedNote note ID |
| `title` | Note title |
| `body` | Full note body text |
| `type` | Note type: `normal` or `video` |
| `image_urls[]` | Array of image URLs |
| `video_url` | Video URL (video notes only) |
| `hashtags[]` | Array of hashtags on the note |
| `author_handle` | Author display handle |
| `author_id` | Author user ID |
| `author_url` | Author profile URL |
| `likes_count` | Number of likes |
| `collects_count` | Number of collects / saves |
| `comments_count` | Number of comments |
| `shares_count` | Number of shares |
| `posted_at` | Original posted-at timestamp |
| `ip_location` | IP location shown on the note |
| `url` | Canonical note URL |
| `data_source` | Source of the record |
| `as_of_timestamp` | When the data was captured |

### ⚖️ Legal & data

This actor collects **public content only** — notes reachable through their public share URL. Note-detail pages **require the share URL's `xsec_token`**; with a wrong or expired token RedNote returns the same 'not found' page it shows for a deleted note, so the actor reports both possibilities and charges nothing. No private, login-gated or personal data is accessed. You are responsible for using the output in compliance with RedNote's terms, applicable laws and any data-protection regulations (e.g. GDPR / PIPL) that apply to you.

### ❓ FAQ

**Q: How do I supply note URLs or IDs?**
Put one or more values in the **Note URLs or IDs** input. You can paste full note URLs, bare note IDs, or mix both. Leave it empty and use **Sample latest feed notes** to pull from the live feed instead.

**Q: Why do I need an `xsec_token`?**
RedNote note-detail pages require a short-lived `xsec_token`. The reliable way to supply it is to **paste the full share URL from the RedNote app or your browser** — it already carries the token (`...?xsec_token=...`). Bare IDs work only when the note is currently present in the live feed, where the token is harvested automatically; otherwise prefer the full URL.

**Q: My run failed with `token_invalid_or_expired` — is the note deleted?**
Partly. With a wrong or expired `xsec_token` RedNote serves the **same 'not found' page as for a deleted note** (verified live 2026-09-03), so the actor cannot tell the two apart. Such notes are reported as "not found OR wrong/expired xsec\_token — re-copy the share URL", the run succeeds with 0 rows for them and **nothing is charged**. A hydrated page that lacks the note without any not-found marker is treated as an access failure (blocked, run fails if nothing else succeeded).

**Q: What does the `feedSample` input do?**
Set **Sample latest feed notes** (`feedSample`) to a number N > 0 (max 50) and the actor tries to harvest the latest N notes from the live RedNote explore feed — each with its own fresh `xsec_token` — and scrapes their full details. This is **best-effort**: the public feed is not always reachable through a proxy, and if the harvest yields 0 notes the run **fails with the reason** (blocked or transport error) rather than returning 0 rows silently. Nothing is charged for a failed harvest. For guaranteed results, supply share URLs.

**Q: Which proxy should I use?**
RESIDENTIAL Apify Proxy is strongly recommended (and prefilled) for reliable access to RedNote.

### 🔗 Related Actors

Part of the NexGenData RedNote matrix:

- [RedNote (Xiaohongshu) Scraper](https://apify.com/nexgendata/rednote-scraper) — trending, user posts, hashtag and keyword search.
- [RedNote (Xiaohongshu) User Profile Scraper](https://apify.com/nexgendata/rednote-user-profile) — full user profile and stats.
- [Xiaohongshu Trends Tracker](https://apify.com/nexgendata/xiaohongshu-trends-tracker) — track trending topics over time.

### 🏢 About NexGenData

NexGenData builds reliable, production-grade scrapers for hard-to-reach platforms. Explore the full catalogue at [NexGenData on Apify](https://apify.com/nexgendata).

***

## 小红书笔记详情采集器 · RedNote (Xiaohongshu) Note Detail Scraper

只需一次调用，即可把任意小红书（RedNote / Xiaohongshu）笔记的链接或 ID 转换为结构化数据：标题、正文、媒体、话题标签、作者以及完整的互动指标。

### ⚡ 功能

| 能力 | 说明 |
| --- | --- |
| 完整笔记详情 | 标题、正文、笔记类型（图文 / 视频）、媒体链接 |
| 互动指标 | 点赞、收藏、评论、分享数 |
| 作者数据 | 昵称、用户 ID 与主页链接 |
| 媒体提取 | 全部图片链接及视频链接（视频笔记） |
| 话题与发现 | 话题标签列表、IP 属地、发布时间 |
| 灵活输入 | 粘贴完整分享链接（含 `xsec_token`）、纯 ID，或尽力采样实时信息流 |
| 诚实计费 | **每成功交付一篇笔记 $0.10 + 每次启动 $0.04。** 被拦截、不存在或未处理的笔记一律不计费 |

### 💰 价格

| 计费项 | 价格 |
| --- | --- |
| Actor 启动 | 每次运行 $0.04 |
| 笔记详情交付（`note-detail`） | 每篇 $0.10 |

仅对已核验 ID 并推送到数据集的真实笔记计费。未交付任何数据的运行会**失败**并在状态信息中说明原因，仅收取启动费。

### 📏 限制与时间预算

- **每次运行最多 50 篇笔记**（`noteUrls` 与 `maxItems` 均上限 50）。更大的列表请分多次运行。
- 运行内置**时间预算**：在运行超时前 45 秒停止开始新的笔记，以便始终能正常收尾。未处理到的笔记会在状态信息中列为 *not processed (time budget)*，且不计费。每篇笔记交付后即逐条计费并推送，即使触及预算，已交付的数据也会保留。

### 🎯 适用场景

- **中国社媒舆情监测** — 为监测到的任意小红书笔记拉取完整详情。
- **KOL / 达人研究** — 获取作者昵称、主页链接及单篇互动数据，用于建立合作名单。
- **消费者与趋势洞察** — 提取正文、话题标签与媒体，分析中国消费者关注的内容。
- **竞品内容审计** — 归档竞争对手的笔记及其指标，长期对比表现。
- **机器学习 / NLP 数据集构建** — 汇总包含文本、媒体与互动信号的结构化中文笔记数据集。

### 🚀 使用方法

**Apify 控制台** — 打开该 Actor，在 **Note URLs or IDs** 中粘贴一个或多个笔记链接（或将 **Sample latest feed notes** 设为一个数字），然后点击 **Start**。结果会保存到运行的数据集中。

**Python（apify-client）**

```python
from apify_client import ApifyClient

client = ApifyClient("<你的_APIFY_TOKEN>")

run_input = {
    "noteUrls": [
        "https://www.xiaohongshu.com/explore/%3CNOTE_ID%3E?xsec_token=%3CTOKEN%3E"
    ],
    "proxyConfiguration": {"useApifyProxy": True, "apifyProxyGroups": ["RESIDENTIAL"]},
}

run = client.actor("nexgendata/rednote-note-detail").call(run_input=run_input)

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)
```

**cURL**

```bash
curl -X POST "https://api.apify.com/v2/acts/nexgendata~rednote-note-detail/runs?token=%3C%E4%BD%A0%E7%9A%84_APIFY_TOKEN%3E" \
  -H "Content-Type: application/json" \
  -d '{
        "noteUrls": ["https://www.xiaohongshu.com/explore/%3CNOTE_ID%3E?xsec_token=%3CTOKEN%3E"],
        "proxyConfiguration": {"useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"]}
      }'
```

### 📊 输出字段

| 字段 | 说明 |
| --- | --- |
| `note_id` | 笔记唯一 ID |
| `title` | 笔记标题 |
| `body` | 笔记正文全文 |
| `type` | 笔记类型：`normal`（图文）或 `video`（视频） |
| `image_urls[]` | 图片链接数组 |
| `video_url` | 视频链接（仅视频笔记） |
| `hashtags[]` | 笔记话题标签数组 |
| `author_handle` | 作者昵称 |
| `author_id` | 作者用户 ID |
| `author_url` | 作者主页链接 |
| `likes_count` | 点赞数 |
| `collects_count` | 收藏数 |
| `comments_count` | 评论数 |
| `shares_count` | 分享数 |
| `posted_at` | 原始发布时间 |
| `ip_location` | 笔记显示的 IP 属地 |
| `url` | 笔记规范链接 |
| `data_source` | 数据来源 |
| `as_of_timestamp` | 数据采集时间 |

### ⚖️ 合规与数据

本 Actor 仅采集**公开内容** —— 可通过公开分享链接访问的笔记。笔记详情页**需要分享链接中的 `xsec_token`**；token 过期时运行会明确失败，而不再把笔记误报为不存在。不会访问任何私密、需登录或个人隐私数据。请您自行确保对输出数据的使用符合小红书的服务条款、适用法律以及对您适用的数据保护法规（如 GDPR / 个人信息保护法 PIPL）。

### ❓ 常见问题

**问：如何提供笔记链接或 ID？**
在 **Note URLs or IDs** 输入框中填入一个或多个值。可以粘贴完整笔记链接、纯笔记 ID，或两者混合。留空并使用 **Sample latest feed notes** 即可改为从实时信息流拉取。

**问：为什么需要 `xsec_token`？**
小红书笔记详情页需要一个时效较短的 `xsec_token`。最可靠的方式是**直接粘贴小红书 App 或浏览器中的完整分享链接** —— 它已携带该 token（`...?xsec_token=...`）。纯 ID 仅在该笔记当前出现在实时信息流时有效（此时 token 会被自动采集）；否则请优先使用完整链接。

**问：运行失败并提示 `token_invalid_or_expired`，笔记被删除了吗？**
没有。`xsec_token` 错误或过期时，小红书返回的页面数据中不包含该笔记。旧版本会将其误报为"不存在"；现在会视为访问失败：运行失败（若其他笔记成功，则在状态信息中将该笔记标记为 blocked），该笔记不计费，解决办法是**重新复制分享链接**以获得新的 token。只有页面带有明确的"不存在"标记时，才会报告笔记确实不存在（SUCCEEDED、0 行、不计费）。

**问：`feedSample` 输入有什么用？**
将 **Sample latest feed notes**（`feedSample`）设为大于 0 的数字 N（最多 50），Actor 会尽力从小红书发现页实时信息流采集最新 N 篇笔记（每篇带有自己全新的 `xsec_token`）并抓取完整详情。这是**尽力而为**的功能：公开信息流并非总能通过代理访问；若采集结果为 0，运行会**带原因失败**（blocked 或传输错误），而不会静默返回 0 行，也不会计费。若需稳定结果，请提供分享链接。

**问：应使用哪种代理？**
强烈建议使用 RESIDENTIAL（住宅）Apify 代理（已默认预填），以稳定访问小红书。

### 🔗 相关 Actor

NexGenData 小红书矩阵的一部分：

- [RedNote (Xiaohongshu) Scraper](https://apify.com/nexgendata/rednote-scraper) — 热门、用户笔记、话题与关键词搜索。
- [RedNote (Xiaohongshu) User Profile Scraper](https://apify.com/nexgendata/rednote-user-profile) — 完整用户主页与统计数据。
- [Xiaohongshu Trends Tracker](https://apify.com/nexgendata/xiaohongshu-trends-tracker) — 长期追踪热门话题。

### 🏢 关于 NexGenData

NexGenData 专注为难以采集的平台打造可靠、生产级的爬虫。在 [Apify 上的 NexGenData](https://apify.com/nexgendata) 浏览完整产品目录。

# Actor input Schema

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

Full share URLs (https://www.xiaohongshu.com/explore/{id}?xsec\_token=...) or bare note ids, max 50 per run. Note-detail pages REQUIRE the share URL's xsec\_token: paste the full URL copied from the RedNote app/browser. An invalid/expired token fails the run loudly (reason token\_invalid\_or\_expired, nothing charged) instead of reporting the note as not found -- re-copy the share URL to get a fresh token. Bare ids are resolved from the live feed only if currently present. Leave empty and use feedSample to pull the latest feed notes. Billing: $0.10 per delivered note + $0.04 actor start.

## `feedSample` (type: `integer`):

Best-effort: if > 0, harvest the latest N notes (max 50) from the live RedNote explore feed, each with its own fresh xsec\_token, and scrape their full details. Feed availability is not guaranteed; if the harvest yields 0 notes the run FAILS with a reason (blocked / transport) and nothing is charged -- it never returns 0 rows silently. 0 (default) disables.

## `maxItems` (type: `integer`):

Max notes to process (hard cap 50 per run). 0 (default) = all supplied notes, still capped at 50. The run also keeps a time budget: it stops starting new notes 45s before the run timeout and lists them in the status message as not processed (time budget); each delivered note is charged and pushed incrementally.

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

Apify proxy. RESIDENTIAL strongly recommended for RedNote. Default exit is pinned to CN residential (apifyProxyCountry=CN) for reliable inside-China egress.

## Actor input object example

```json
{
  "noteUrls": [],
  "feedSample": 0,
  "maxItems": 0,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "CN"
  }
}
```

# 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 = {
    "noteUrls": [],
    "feedSample": 0,
    "maxItems": 0,
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ],
        "apifyProxyCountry": "CN"
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("nexgendata/rednote-note-detail").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 = {
    "noteUrls": [],
    "feedSample": 0,
    "maxItems": 0,
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
        "apifyProxyCountry": "CN",
    },
}

# Run the Actor and wait for it to finish
run = client.actor("nexgendata/rednote-note-detail").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 '{
  "noteUrls": [],
  "feedSample": 0,
  "maxItems": 0,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "CN"
  }
}' |
apify call nexgendata/rednote-note-detail --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nexgendata/rednote-note-detail"
        }
    }
}

```

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/HSvdXoO9eiZT1qTIW/builds/P7NqWmW5TB7aWpq8b/openapi.json