小红书数据 API | SocialDataX Xiaohongshu XHS RedNote

这是社媒数据助手 SocialDataX 的 Apify Actor，提供只读小红书 / Xiaohongshu / XHS / RedNote data API。

适合高意图场景：Xiaohongshu search / RedNote search、按关键词搜索笔记或商品、商品评价研究、话题趋势分析、评论导出、笔记详情、博主作品与资料研究，并直接导出为 Apify Dataset、CSV、Excel。

Apify 用户无需配置 SocialDataX API Key；直接通过 Apify Console、Apify API、Dataset export 或自动化工作流运行即可。

支持能力：

• 用户搜索 / user search
• 搜索词建议 / search suggestions
• 商品评价回复及嵌套回复 / product review replies
• 笔记搜索 / note search
• 商品搜索 / product search
• 商品详情 / product details
• 商品评价 / product reviews
• 标签页笔记 / topic notes
• 评论导出 / comments export
• 笔记详情 / note details
• 分享信息 / share info
• 博主作品列表 / creator posts
• 博主信息 / creator profiles
• 评论回复 / comment replies
• 搜索热榜 / search hot list

This Actor is a read-only, unofficial data API integration. It is not affiliated with Xiaohongshu, XHS, or RedNote.

用户作品列表的 is_pinned 表示该作品是否在此用户主页置顶（true / false），可在 Overview 和作品列表视图查看；字段缺失时表示接口未提供，不能据此确认作品未置顶。Actor 保留接口返回的顺序和分页。

Support / 联系我们

如果 run 失败、需要更高用量，或想接入批量数据工作流，请通过 SocialDataX support 联系我们：

• Website: https://socialdatax.com/ai?from=apify

If a run fails, you need higher limits, or you want to discuss a bulk data workflow, contact SocialDataX support:

• Website: https://socialdatax.com/ai?from=apify

选择字段

先选择 operation，再填写该 operation 需要的字段。Apify 表单里其它字段可以留空；即使误填了无关字段，Actor 也会忽略。

Operation	必填字段	可选字段	说明
search_notes	keyword	page_token, sort_type, note_type, publish_time_range, max_items, auto_paginate	关键词笔记搜索，默认会自动翻页直到达到 max_items。第一页 page_token 留空，继续翻页时使用上一页 Dataset 行的 page_next_page_token。
search_images	keyword	page_token, max_items, auto_paginate	按关键词搜索图片，每张图片一条结果；同一笔记的互动数不要重复累加。分页令牌仅用于同一关键词的图片搜索。
search_users	keyword	page_token, max_items, auto_paginate	搜索博主或账号，返回的 user_id 可用于用户资料和作品列表。
search_suggestions	keyword	max_items	获取候选搜索词，每条为 text、search_target、description；只请求一次，不自动执行搜索。
get_product_review_replies	review_id	page_token, max_items, auto_paginate	读取一级商品评价下的回复；使用 get_product_reviews 返回的 review_id。
get_product_review_reply_replies	review_id	page_token, max_items, auto_paginate	读取某条回复下的嵌套回复；使用 get_product_review_replies 返回的回复自身 review_id，不要用 root_review_id。
search_products	keyword	page_token, max_items, auto_paginate	按商品名、品牌或品类搜索商品，并将商品、价格和店铺字段写入 Dataset。
get_product_detail	sku_id 或 url 至少填一个	无	通过完整 SKU ID、商品链接或分享文案获取详情，无需先搜索；两者都填时优先使用 url。
get_product_reviews	sku_id	sort_type, has_image, page_token, max_items, auto_paginate	获取商品评价；支持综合/最新排序和仅看带图评价。
get_note_comments	note_id 或 note_url 至少填一个	sort_type, page_token, max_items, auto_paginate	获取一级评论列表；两者都填时优先使用 note_url。sort_type 支持 default, time_descending, like_count_descending。
get_share_info	share_text	无	从笔记分享短链接或完整分享文案获取分享人、笔记摘要和作者；单次请求、一条 Dataset 结果，不包含分享时间。完整笔记内容请使用 get_note_detail。
get_note_detail	note_id 或 note_url 至少填一个	无	获取单篇笔记详情；两者都填时优先使用 note_url。
list_user_notes	user_id 或 profile_url 至少填一个	page_token, max_items, auto_paginate	获取博主作品列表；两者都填时优先使用 profile_url。
get_user_info	user_id 或 profile_url 至少填一个	无	获取博主信息；两者都填时优先使用 profile_url。
get_note_sub_comments	note_id, comment_id	page_token, max_items, auto_paginate	获取某条一级评论下的回复。先运行 get_note_comments，从 Dataset 的 comment_id 字段复制有 reply_count > 0 的一级评论 ID。
list_topic_notes	page_id 或 topic_url 至少填一个	sort_type, page_token, max_items, auto_paginate	获取话题标签页下的笔记；支持 hot 和 time_descending 排序。
search_hot_list	无	max_items	搜索热榜，请求一次并按 max_items 限制写入 Dataset。

字段填写建议 / Input tips

商品搜索和详情的 sales_text 保留平台销量展示文本；sold_count 在无法解析或缺失时为 null，真实零销量才为 0，例如 已售1.2万+ 的 12000 只是下限。搜索 price 是展示销售价，详情 price 是当前 SKU 原价；coupon_price 是展示券后/成交价，不能保证是最终实付价。详情 specifications 是 name/value 商品参数；库存状态码 stock_status 含义未定义，不要据此推断是否在售或可购买。

• note_url: 推荐直接粘贴小红书笔记链接、短链接或分享文案，适用于 get_note_detail 和 get_note_comments。get_note_sub_comments 不使用 note_url，请先跑 get_note_comments 再复制 Dataset 行里的真实 note_id + comment_id。
• profile_url: 推荐直接粘贴小红书主页链接、短链接或分享文案，适用于 get_user_info 和 list_user_notes，无需先提取或转换用户 ID。
• note_id: 只填真实笔记 ID；如果把笔记链接或分享文案误填到 note_id，Actor 会尽量自动按 note_url 处理。get_note_sub_comments 例外，它必须使用 get_note_comments Dataset 行里的真实 note_id。
• user_id: 已有用户 ID 时直接原样填写，无需先转换。支持完整的 24 位或 29 位小写十六进制 ID。不要填昵称、主页名称或小红书号；如果只有主页链接或分享文案，请填 profile_url。
• sku_id: 用户已提供完整商品 SKU ID 时直接使用，否则从 search_products 或 get_product_detail 获取；此字段不接受 spu_id、商品链接或搜索词。商品评价仍必填 sku_id。
• url: 商品详情 get_product_detail 支持商品详情链接、短链接或包含商品链接的完整分享文案；至少提供 sku_id 或 url 之一，同时提供时优先使用 url。Dataset 的 query_url 与运行摘要的 query.url 保留实际使用的链接或分享文案。
• topic_url: 推荐直接粘贴小红书话题页链接、短链接或分享文案；也可使用完整 page_id。
• sort_type: search_notes 支持内容搜索排序；get_note_comments 支持评论排序；get_product_reviews 支持 general, time_descending；list_topic_notes 支持 hot, time_descending。为兼容共享表单，search_notes 和 get_product_reviews 的 default 按 general 处理，get_note_comments 的 general 按 default 处理，list_topic_notes 的 general / default 按 hot 处理。
• page_token: 笔记/商品搜索、商品评价、标签页笔记、评论、评论回复、博主作品列表继续翻页时，原样使用上一页 Dataset 行的 page_next_page_token（对应 API 返回的 next_page_token）；第一页留空。开启 auto_paginate=true 时通常不用手动填写。list_user_notes 续页须保持首屏的输入用户 ID 不变，即使对应同一用户，也不能换成结果返回的另一种 ID。
• comment_id: 只填 get_note_comments Dataset row 里的 comment_id。请选择 reply_count > 0 的一级评论行，不要填评论内容、昵称或其它文本。

如果用户把笔记链接填到博主类 operation、把主页链接填到笔记类 operation、在 list_topic_notes 中填入明确的笔记/主页链接，或在 get_note_sub_comments 的 note_id 里粘贴笔记链接/分享文案，Actor 会跳过 SocialDataX API 请求并在 OUTPUT 写入中英文 warning 和支持链接，避免因为明显可修正的输入问题直接失败。

输入示例

用户搜索和搜索词建议：

{"operation":"search_users","keyword":"露营","max_items":20,"auto_paginate":false}

{"operation":"search_suggestions","keyword":"露营","max_items":10}

建议中的 search_target=notes 可使用 search_notes，search_target=goods 可使用 search_products，将建议的 text 填入 keyword；Actor 不自动调用下一步。

商品评价回复先从 get_product_reviews 结果获取 review_id，再运行 get_product_review_replies。继续读取某条回复下的嵌套回复时，将那条回复自身的 review_id 传给 get_product_review_reply_replies。两种操作都支持 page_token、max_items 和 auto_paginate；没有回复时 Dataset 可以为空。

笔记搜索：

{
  "operation": "search_notes",
  "keyword": "露营",
  "page_token": "",
  "sort_type": "general",
  "note_type": "all",
  "publish_time_range": "all",
  "max_items": 20,
  "auto_paginate": true
}

商品搜索：

{
  "operation": "search_products",
  "keyword": "露营桌",
  "max_items": 20,
  "auto_paginate": true
}

商品详情：

{
  "operation": "get_product_detail",
  "sku_id": "691c1de31896c300014f6ea8"
}

也可以直接传商品分享链接（url 同样接受完整分享文案）：

{
  "operation": "get_product_detail",
  "url": "https://xhslink.com/m/2x9XPGwSH6S"
}

商品评价：

{
  "operation": "get_product_reviews",
  "sku_id": "691c1de31896c300014f6ea8",
  "sort_type": "general",
  "has_image": false,
  "max_items": 20,
  "auto_paginate": true
}

标签页笔记：

{
  "operation": "list_topic_notes",
  "topic_url": "https://www.xiaohongshu.com/topic/normal/60e27aef15d4f70001dd8d7b",
  "sort_type": "hot",
  "max_items": 20,
  "auto_paginate": true
}

搜索热榜：

{
  "operation": "search_hot_list",
  "max_items": 20
}

笔记详情：

{
  "operation": "get_note_detail",
  "note_url": "https://www.xiaohongshu.com/discovery/item/69e71b110000000022029e5e?xsec_source=app_share&xsec_token=CB8LYwuNCmdLCh4IingDx12rfddpSYoSu-dkiRRHnsk6o="
}

评论列表：

{
  "operation": "get_note_comments",
  "note_url": "https://www.xiaohongshu.com/discovery/item/69e71b110000000022029e5e?xsec_source=app_share&xsec_token=CB8LYwuNCmdLCh4IingDx12rfddpSYoSu-dkiRRHnsk6o=",
  "sort_type": "default",
  "page_token": "",
  "max_items": 20,
  "auto_paginate": true
}

评论回复：

{
  "operation": "get_note_sub_comments",
  "note_id": "69e71b110000000022029e5e",
  "comment_id": "69e85611000000001401c821",
  "page_token": "",
  "max_items": 20,
  "auto_paginate": true
}

comment_id 来自 get_note_comments 的 Dataset 结果。选择 reply_count > 0 的一级评论行，复制该行的 comment_id。

博主信息：

{
  "operation": "get_user_info",
  "profile_url": "https://www.xiaohongshu.com/user/profile/67c25fdc000000000a03dae1"
}

博主作品列表：

{
  "operation": "list_user_notes",
  "profile_url": "https://www.xiaohongshu.com/user/profile/67c25fdc000000000a03dae1",
  "page_token": "",
  "max_items": 20,
  "auto_paginate": true
}

max_items 默认 20，最大 1000。auto_paginate=false 时只请求当前 page_token。搜索热榜不需要分页参数，Actor 会请求一次，并按 max_items 限制写入 Dataset 的热榜条目数。

如果用户在 Apify run options 里设置了更低的 paid Dataset item 上限，Actor 会把列表类 max_items 自动裁剪到该上限，避免超预算请求过多页面。 如果该上限为 0，Actor 会直接结束并在 OUTPUT 写入 warning，不会请求 SocialDataX API。

Apify 计划要求

持续使用需要 Apify paid plan。Apify free plan 用户有 5 次 SocialDataX API request 试用额度；每次请求一个接口页面计 1 次，auto_paginate=true 时每翻一页都会计入一次。试用额度用完后，请升级 Apify 计划继续使用。

Ongoing use requires an Apify paid plan. Free-plan users get a 5-request SocialDataX API trial. Each requested page counts as one request, so auto_paginate=true can consume multiple requests in one run.

输出

Actor 会把结果写入 Apify Dataset，适合 JSON、CSV、Excel / XLSX、JSONL 等格式导出。

列表类接口会为 items[] 中的每个元素写入一条扁平 dataset row：

{
  "operation": "get_note_comments",
  "item_index": 1,
  "query_note_id": "69e71b110000000022029e5e",
  "query_sort_type": "default",
  "query_page_token": "",
  "query_max_items": 20,
  "query_auto_paginate": true,
  "comment_id": "69e85611000000001401c821",
  "content": "这个清单很实用。",
  "author_user_id": "ae33373e21b0ef7d235fa646c95b7",
  "author_name": "D.",
  "page_request_index": 1,
  "page_item_count": 20,
  "page_next_page_token": "next-token",
  "page_has_more": true
}

详情类接口会写入一条 dataset row。author、video 等常见对象会展开为 author_*、video_* 字段；图片、话题、数组字段保留 JSON 值。

如果某一页 items 为空但仍有 page_next_page_token，且本次 run 没有继续拿到后续实际 item，Actor 会写入一条 empty_page=true 的摘要行。自动翻页后拿到后续实际 item 时，中间空页不会写入 Dataset row，也不会占用 max_items；没有下一页的终止空页不会写入 Dataset row。

如果 max_items 或计费上限导致最后一页只导出部分结果，OUTPUT.warnings 会提示页内截断。page_next_page_token 按整页推进，使用它续采会跳过该页未导出的结果，不支持从截断位置接着导出。需要完整续采时，请用该页的 query_page_token 重新请求，确保本次上限足以导出整页，并对已保存结果去重；图片搜索按 image_id 去重。

如果 run 失败，OUTPUT 会保留一条轻量失败摘要，方便在 Apify 控制台里直接看到请求次数、状态码和简要错误信息。

Apify API 调用

同步运行并直接获取 Dataset items：

curl -X POST "https://api.apify.com/v2/acts/socialdatax~socialdatax-xhs-data-api/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "search_notes",
    "keyword": "露营",
    "page_token": "",
    "max_items": 20,
    "auto_paginate": true
  }'

Python client 示例：

from apify_client import ApifyClient

client = ApifyClient("<APIFY_TOKEN>")
run = client.actor("socialdatax/socialdatax-xhs-data-api").call(run_input={
    "operation": "search_notes",
    "keyword": "露营",
    "page_token": "",
    "max_items": 20,
    "auto_paginate": True,
})
items = client.dataset(run["defaultDatasetId"]).list_items().items

费用

Apify 用户按 Actor 页面展示的 Apify 价格和用量计费，不需要购买或配置 SocialDataX API Key。

图片搜索 / Image search

operation: "search_images"；必填字段：keyword。按关键词搜索图片，每张图片一条结果；同一笔记的多张图片共享 note_id，笔记互动数不要重复累加。

使用 max_items 限制输出条数，沿用现有 Dataset 条目计费规则。支持 page_token 和 auto_paginate；分页令牌仅用于同一关键词的图片搜索，不能与笔记搜索互用。

分享信息 / Share info

{"operation":"get_share_info","share_text":"粘贴实际的小红书笔记分享短链接或包含该链接的完整文案"}

在 Share info overview 查看 share_user_info（分享人）和 note_info（笔记摘要及 author 作者）。分享人与作者分别记录，可能是同一人。两个顶层对象均允许为 null，成功结果至少有一个非空对象；对象字段会原样保留在 Dataset 和 JSON 导出中。