RedNote API – Xiaohongshu Keyword Scraper & Search Data Extractor

RedNote API is an Apify Actor that scrapes Xiaohongshu (小红书) / RedNote keyword search results with Playwright. Extract posts, authors, engagement metrics, and media URLs per keyword. Export structured rows to the default dataset as JSON, CSV, or Excel.

Overview

Each run processes your keywords (with optional concurrency), pushes one dataset item per post (or per keyword error), and never stops the whole run when a single keyword fails.

• Browser automation — handles dynamic JavaScript search pages
• Fast or rich mode — search cards only, or optional detail-page enrichment
• Secret session inputs — storageStateJson, cookiesJson, and KV/file paths are encrypted in Apify storage
• Residential proxy — recommended via proxyConfiguration
• Automation-ready — API, schedules, and webhooks

Quick start

1. Open RedNote API on Apify and add one or more keywords (e.g. skincare).
2. Set maxItems per keyword and enable residential proxy in proxyConfiguration.
3. For production: paste a logged-in session into storageStateJson (recommended) or cookiesJson.
4. Click Run — inspect the Dataset tab (overview view) for post rows.
5. Export via Console or the dataset API link in the actor Output schema.

Minimal input example (health check / Try actor)

Default prefills are tuned to finish in under 5 minutes without a session. An auth error row is expected when no session is provided.

{
  "keywords": ["coffee"],
  "maxItems": 2,
  "includeDetails": false,
  "exportStorageState": false,
  "proxyCountry": "AUTO_SELECT_PROXY_COUNTRY",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"],
    "apifyProxyCountry": "US"
  },
  "headless": true,
  "maxConcurrency": 1
}

Input configuration

Field	Required	Description
keywords	Yes	One or more search keywords (string list). Prefill: ["coffee"].
maxItems	No	Max posts per keyword (default 20, max 200). Prefill: 2.
proxyConfiguration	No	Apify proxy settings. Default/prefill: residential US.
proxyCountry	No	AUTO_SELECT_PROXY_COUNTRY, country code, or DISABLED.
baseDomain	No	www.xiaohongshu.com or www.rednote.com (alternate auto-retried on failure).
storageStateJson	No	Secret. Full Playwright storage_state JSON string — recommended for logged-in search.
storageStatePath	No	Secret. Local file path or Apify KV store key containing storage state JSON.
cookiesJson	No	Secret. Playwright cookie array JSON for .xiaohongshu.com / .rednote.com.
cookiesFile	No	Secret. Local file path or KV key containing cookies JSON.
includeDetails	No	Open each post detail page for richer fields (default false; slower).
includeAuthor	No	Extract author nickname, id, avatar (default true).
includeMedia	No	Extract images and video URLs (default true).
maxConcurrency	No	Keywords processed in parallel (default 1, max 5).
headless	No	Headless browser (default true).
sortBy	No	general or latest (ignored safely if unsupported).
exportStorageState	No	Local only. Headed browser to save storage_state.json after manual login.
storageState / cookies	No	Legacy JSON editors. Prefer secret string fields above in Apify Console.

Production input example (with session & proxy)

{
  "keywords": ["skincare", "travel outfit"],
  "maxItems": 20,
  "baseDomain": "www.xiaohongshu.com",
  "proxyCountry": "AUTO_SELECT_PROXY_COUNTRY",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"],
    "apifyProxyCountry": "US"
  },
  "storageStateJson": "{\"cookies\":[...],\"origins\":[...]}",
  "includeDetails": false,
  "includeAuthor": true,
  "includeMedia": true,
  "sortBy": "general",
  "headless": true,
  "maxConcurrency": 1
}

Alternative: store session JSON in a KV record and pass the key name in storageStatePath or cookiesFile instead of pasting secrets inline.

Output

Results are stored in the default dataset. Use the actor Output schema in Console for the dataset API link (?view=overview).

Dataset fields (success rows)

Field	Description
keyword	Search keyword for this row
post_id / post_url	Note identifier and detail URL
title / description	Post caption and description
author_name / author_id	Author profile fields
liked_count / comment_count / share_count / collected_count	Engagement metrics
images / image_count / video_url / cover_image	Media URLs
search_url / scraped_at / source	Provenance metadata
item	Nested note_card, interact_info, tags, timestamps

Example success row

{
  "keyword": "skincare",
  "search_url": "https://www.xiaohongshu.com/search_result?keyword=skincare&source=web_search_result_notes&type=51",
  "post_id": "64f1a2b3c4d5e6f7890",
  "post_url": "https://www.xiaohongshu.com/explore/64f1a2b3c4d5e6f7890",
  "title": "My daily skincare routine",
  "author_name": "Alice",
  "liked_count": 1234,
  "images": ["https://example.com/image1.jpg"],
  "image_count": 1,
  "scraped_at": "2026-06-06T12:00:00.000Z",
  "source": "xiaohongshu",
  "item": {
    "id": "64f1a2b3c4d5e6f7890",
    "note_card": { "display_title": "My daily skincare routine" }
  }
}

Error rows

Failed keywords produce a row with error (and often requiresAuth: true when no session was provided). Other keywords still run.

{
  "keyword": "coffee",
  "url": "https://www.xiaohongshu.com/search_result?keyword=coffee&source=web_search_result_notes&type=51",
  "error": "Xiaohongshu / RedNote search usually requires a logged-in session...",
  "requiresAuth": true,
  "scraped_at": "2026-06-06T12:00:00.000Z"
}

Empty values are omitted from each row for cleaner dataset tables.

How it works

1. Playwright launches Chromium with optional Apify residential proxy.
2. Session cookies/localStorage are loaded from storageStateJson, storageStatePath, or cookiesJson / cookiesFile.
3. For each keyword, the Actor opens search results, scrolls the feed, and parses post cards from the DOM.
4. When includeDetails is true, each note detail page is visited for richer fields.
5. Each post (or keyword error) is sanitized and pushed to the default dataset.
6. On failure, the Actor retries per keyword and may try the alternate domain (rednote.com ↔ xiaohongshu.com).

Authentication & sensitive input

Fields that can hold session credentials use Apify secret input (isSecret: true):

• storageStateJson — full Playwright storage state (recommended)
• storageStatePath — file path or KV key for storage state
• cookiesJson — Playwright cookie array JSON
• cookiesFile — file path or KV key for cookies

Secret values are encrypted in storage and are not copied into dataset rows or logs.

Keyword search usually requires a logged-in session. Export a session locally with exportStorageState: true, then paste the JSON into storageStateJson or upload it to a KV store and set storageStatePath.

Apify Console health check

After deploying build 0.3+, use Try actor with default prefilled input:

• keywords: ["coffee"], maxItems: 2, includeDetails: false
• Residential proxy via proxyConfiguration (US prefill)
• No session — validates startup, proxy, and browser flow in under 5 minutes
• Expected: exit code 0 with an auth error row or demo fallback row (not live post rows)

Log marker: SCRAPER_BUILD_MARKER=v3-health-fast-fail

Best practices

• Provide storageStateJson from a browser where you are already logged in before production keyword runs.
• Use residential proxy in a region consistent with the account that created the session.
• Keep maxConcurrency at 1 unless you accept higher block risk.
• Start with includeDetails: false; enable detail enrichment only when you need full post pages.
• Try www.rednote.com if xiaohongshu.com is blocked in your region.
• Respect platform terms, applicable laws, and reasonable scrape volume.

Use cases

• Social media research and keyword trend monitoring
• Brand and product mention tracking on Xiaohongshu / RedNote
• Influencer and engagement benchmarking
• Data pipelines (warehouse, BI, ML) via Apify API or scheduled runs

Limitations

• Login walls — keyword search typically fails without storageStateJson or cookies.
• Anti-bot — success depends on proxy quality, session freshness, and site changes.
• No official API — DOM changes may require Actor updates.
• Detail mode cost — includeDetails: true opens one page per post (much slower).
• Concurrency risk — values above 1 increase blocking probability.

FAQ

What is RedNote API used for?

Scraping Xiaohongshu / RedNote keyword search results — posts, authors, engagement, and media — for research and analytics on Apify.

Can I scrape without an official API?

Yes. The Actor uses Playwright against the public web interface.

Why am I getting empty results or auth errors?

Login walls and blocking are common. Add storageStateJson or cookiesJson, use residential proxy, and keep concurrency low.

Can I scrape multiple keywords in one run?

Yes. Each keyword is processed independently; one failure does not stop others.

What is detail enrichment?

When includeDetails is true, the Actor visits each post URL for fuller title, description, and media fields.

How do I save a logged-in session?

Locally: set exportStorageState: true, log in when the browser opens, then use the saved JSON in storageStateJson or upload to KV and set storageStatePath.

Does the health check need post rows?

No. Prefilled runs validate Actor startup and browser flow. An auth error row with exit code 0 is a successful health check.

Where do I export results?

Apify dataset tab (JSON, CSV, Excel) or the dataset API link from the actor Output schema.

Run locally

1. cd rednote-api
2. pip install -r requirements.txt
3. playwright install chromium
4. Create INPUT.json in this folder (see examples above).
5. apify run or run main.py in an Apify-compatible environment.

Use exportStorageState: true locally to capture a session, then re-run with storageStatePath.

Deploy

Push with Apify CLI or connect the Git repository (rednote-api/ directory). Schema files: INPUT_SCHEMA.json, .actor/dataset_schema.json, .actor/output_schema.json, Dockerfile.

Get started

Add your keywords, enable residential proxy, paste a logged-in storageStateJson for production runs, and export Xiaohongshu / RedNote search data on Apify.