Xiaohongshu Note Research API Tutorial | SandBase
Make one Xiaohongshu note research request: search a keyword or read the first comments page for a known note ID, with checked responses and historical evidence.

A category researcher with a keyword and a community manager with a known note ID need different first requests. Searching again when you already have the note adds work and may select the wrong post. This Xiaohongshu note research API tutorial starts with that choice: fetch one search page, or fetch one comments page for the note you already chose.
The current setup was checked against SandBase’s schemas and public reference examples on 2026-11-08. No paid business request was run for this update. The wider sunscreen research experiment below was tested on 2026-10-01 UTC; its results remain historical evidence, not a fresh availability test. The Xiaohongshu API hub maps other endpoints, while the product research guide covers products and SKUs rather than notes.
Key takeaway
- Choose keyword search or known-note comments; the example makes exactly one request.
- Both use Model API POST routes and read only the documented
outputs[0].dataenvelope.- The current search reference has
code: 0anddata.itemswithout asuccessflag; comments hascode: 0,success: trueanddata.comments.- Preserve missing counts as unknown. A first page is a sample, not a category ranking or a complete discussion.
Choose your Xiaohongshu note research API request
| What you already have | Endpoint | First-page input |
|---|---|---|
| A topic or product-category keyword | Search notes | Required keyword; page: 1; empty search IDs |
| A known public note ID | Note comments | note_id; empty cursor; index: 0; pageArea: "UNFOLDED" |
Search defaults to ai_mode: 0 and sort_type: "general". Its other schema defaults are source: "explore_feed", note_type: "不限" and time_filter: "不限"; the short example leaves those three to the server. It does not invent extra filter values. Comments defaults to sort_strategy: "latest_v2". The comments schema lists note_id and share_text as optional fields, while the reference explains that one identifies the target. This helper deliberately requires a known note ID and leaves share-link parsing outside its scope.
A token caveat matters here. The search reference associates xsec_token with detail and comment access, but this exact app-v2/note-comments request schema declares no such parameter. Do not add a guessed xsec_token field, ask a customer for a login cookie, or copy tokens into an agent prompt. Different Xiaohongshu routes have different contracts; the historical web-v3 failure below does not change this app-v2 request.
Connect the project you already have
If you already have a SandBase key, keep it in the local SANDBASE_API_KEY environment variable or your project’s existing secret store. If your agent is already connected to SandBase, reuse that connection and inspect the selected endpoint instead of provisioning another key. For a new project, give your agent the setup skill and Markdown quickstart, plus the task and keyword or note ID. The key itself stays out of the conversation.
A useful instruction is: “Use my existing SandBase connection to fetch the first Xiaohongshu search page for my keyword. Inspect the schema first, make one request, and report an error instead of retrying, paging, selecting notes or calling an LLM.” For comments, replace the task with the known note ID and first comments page. This makes the cost and stopping point reviewable before adding a larger workflow.
For Python, install requests with python3 -m pip install requests, save the example as first_request.py, then run python3 first_request.py after setting your key locally. The shipped main block runs search only. To choose comments instead, replace those two lines with result = first_request("comments", os.environ.get("XIAOHONGSHU_NOTE_ID")) and print("Comments:", len(result["data"]["comments"])); set that ID locally first. Do not append a second request accidentally.
One request, with a checked response
The route is POST /v1/api/xiaohongshu/app-v2/<operation>, not the catalog’s GET surface. The JSON body contains the selected endpoint’s parameters. This helper follows the two current reference samples; it is not a universal Xiaohongshu success-code mapper.
import os
import re
import requests
def first_request(task, value):
if not isinstance(value, str) or not value.strip():
raise ValueError("Provide a keyword or a known note_id")
if task == "search":
path, field = "search-notes", "items"
params = {"keyword": value.strip(), "page": 1,
"search_id": "", "search_session_id": "",
"ai_mode": 0, "sort_type": "general"}
elif task == "comments":
if not re.fullmatch(r"[0-9a-fA-F]{24}", value):
raise ValueError("Use a known 24-character hex note_id, not a URL")
path, field = "note-comments", "comments"
params = {"note_id": value, "cursor": "", "index": 0,
"pageArea": "UNFOLDED", "sort_strategy": "latest_v2"}
else:
raise ValueError("Choose search or comments")
key = os.environ.get("SANDBASE_API_KEY", "").strip()
if not key:
raise RuntimeError("Set SANDBASE_API_KEY locally")
try:
response = requests.post(
f"https://api.sandbase.ai/v1/api/xiaohongshu/app-v2/{path}",
headers={"Authorization": f"Bearer {key}"}, json=params,
timeout=(10, 90), allow_redirects=False,
)
if not 200 <= response.status_code < 300:
raise RuntimeError(f"SandBase HTTP {response.status_code}")
body = response.json()
except ValueError:
raise RuntimeError("SandBase returned invalid JSON") from None
except requests.RequestException:
raise RuntimeError("SandBase network request failed; not retried") from None
if not isinstance(body, dict) or body.get("status") != "completed":
raise RuntimeError("SandBase request did not complete")
outputs = body.get("outputs")
if not isinstance(outputs, list) or not outputs or not isinstance(outputs[0], dict):
raise RuntimeError("Missing documented outputs[0].data")
payload = outputs[0].get("data")
if not isinstance(payload, dict):
raise RuntimeError("Missing documented outputs[0].data")
if type(payload.get("code")) is not int or payload["code"] != 0:
raise RuntimeError("Unexpected Xiaohongshu provider status")
if "success" in payload and payload["success"] is not True:
raise RuntimeError("Xiaohongshu provider reported failure or malformed success")
data = payload.get("data")
if not isinstance(data, dict) or not isinstance(data.get(field), list):
raise RuntimeError(f"Missing Xiaohongshu data.{field} list")
if any(not isinstance(item, dict) for item in data[field]):
raise RuntimeError(f"Malformed Xiaohongshu data.{field} entry")
return payload
if __name__ == "__main__":
result = first_request("search", "sunscreen")
print("Search items:", len(result["data"]["items"]))An empty list is a valid first-page result here; a missing list, wrong shape, failed status or absent envelope is an error. The helper accepts the search reference’s absent success flag, rejects an explicit failure on either endpoint, and checks the integer code separately. It does not convert a malformed response into “no notes.” A different provider contract should prompt investigation rather than a new silent fallback.
The success printout is only the number of items on this returned page. It may include non-note cards, and it does not claim a total or extract user identities. The full payload remains available to your application without replacing absent metrics with zero. Timeouts, redirects, HTTP errors and invalid JSON stop after one attempt; errors do not echo authorization headers or provider payloads. Check credentials for 401/403, account/balance context for 402, and rate limits for 429 before deciding on a separate attempt.
Cost and the limit of this refresh
The free inspect snapshots on 2026-11-08 show a $0.01 base price per call for each of these two endpoints and eligibility for the organization’s 100 daily free calls shared across eligible data APIs, resetting at 00:00 UTC. Remaining quota was not queried. One request is therefore a $0.01 base-price estimate before any applicable quota; it is not a promise that this request will be free. Inspect current pricing before extending the workload.
Neither pagination, note detail nor a chained report was executed during this refresh. Search’s published sample is trimmed and does not establish a complete next-page handoff. Comments’ example also truncates its cursor. A truncated reference token cannot be used as a continuation token. The older pagination observations below explain the original experiment, not a tested continuation recipe for today.
Historical experiment: sunscreen notes, 2026-10-01
The original experiment expanded a seed, searched two pages, inspected selected notes and sampled comments. Its verbatim code archive preserves both locales’ six Python blocks with SHA256 records. Those blocks contain obsolete top-level output fallback, automatic retries, paging and missing-count zero filling. They are archived evidence, not executable current guidance. The runnable helper above replaces that path.
Historical catalog screenshot, 2026-10-01. Its endpoint count and Free promotion label describe that capture, not current pricing. The example above uses Model API POST routes.
Keyword and search observations
For 防晒霜 (sunscreen), run 74a3e360-568a-4688-b9c4-f347d630a1a0 suggested recommendations, non-greasy sunscreen, application instructions, men’s sunscreen and military-training sunscreen. That was a web-v3/search-suggest experiment, not part of this update. It used provider code: 1000 with success: true; that does not make 1000 a valid success code for the two app-v2 samples used by the new helper.
Search page 1 (829c7829-b1d4-4588-abcb-bdabd4f2a16a) returned 20 items plus page: 1, next_page: 2, search_id and search_session_id beside data. Page 2 (c578ddab-1bfe-42f9-ac33-509e5bb39206) returned 20 more with the same IDs and next_page: 3. One card had model_type: "ads"; two-page runs produced 40 unique notes once and 30 another time. This is evidence of sampling drift, not a stable ranking. Historical card counts and identity fields were observed-only; the new helper makes no ranking or identity export.
Historical search reference, 2026-10-01: keyword and pagination parameters. The old empty response example is superseded by the current public sample checked for this update.
Detail observations and a wrong-note trap
The old image-detail response contained a wrapper with note_list; video detail had a flat list. Sending an image note to the video route produced code: 0 and unrelated videos (fd0b3c04-618a-4a9b-8098-153badd96660). A transport success did not establish that the requested resource had been returned. These routes are outside the current runnable flow.
This trimmed public brand-note sample came from f90a6662-0eb4-49b5-a76b-88ffe488d085, with identical counts observed again in 640fbaba-3390-4935-a269-08ba2162937c on the historical test date:
{
"code": 0,
"success": true,
"data": [
{
"model_type": "note",
"note_list": [
{
"id": "6a749cd70000000005021fd8",
"type": "normal",
"title": "莎莎周边已就位!晒单抽亲签💙",
"desc": "夏日养肤,谁还没用这套!\n维稳抗应激、深层修护、清洁净肤……",
"liked_count": 4297,
"collected_count": 136,
"comments_count": 193,
"shared_count": 86,
"time": 1786071657,
"ip_location": "Shanghai",
"view_count": 0,
"hash_tag": [
{"name": "理肤泉B5面膜PRO", "type": "topic"},
{"name": "理肤泉超级B5精华", "type": "topic"}
],
"user": {"nickname": "理肤泉larocheposay", "red_official_verified": false}
}
]
}
]
}The observed view_count: 0 did not establish zero actual views. The brand account also had red_official_verified: false; that flag did not identify all brand accounts. Neither value is a sound shortcut for ranking. If a metric is absent, preserve it as unknown; compute a ratio only with known values and a positive denominator. The historical image-detail route also returned a video note without its video-info block, but that single result does not validate a fallback today.
Historical image-detail reference, 2026-10-01. This endpoint belongs to the archived experiment; it is not called by the current helper.
Comment observations
The historical brand-note experiment tried the returned JSON-string cursor unchanged (dbfada10-3360-4a16-a0fd-e0cd1b2db866) and its parsed fields (a01020cc-24ea-4d94-aea9-64bfa31b921e); both returned the same next 10 comments then. The current first-page helper uses neither continuation approach. Pagination needs a complete fresh response and a separate verification step.
With like_count sorting in that experiment, the first comment had 0 likes and 18 replies; subsequent comments had 97, 41 and 30 likes. The order was not strictly numeric. Counts and reply fields were observed-only. A comment sample can suggest questions to investigate, but it cannot represent every viewer’s opinion or prove purchase intent.
Historical comments reference, 2026-10-01: cursor, index, note_id, pageArea, share_text and sort_strategy. Current first-page defaults were separately checked on 2026-11-08.
The historical report, not a current benchmark
The 2026-10-01 research_topic("防晒霜") run used search runs be1bcdab-01f0-41c8-ba6c-7d64f74ab394 and 1ad8a233-75c2-4054-afa0-14e8396eb072: 30 unique notes, 23% videos and a median of 84 likes. Three of the top five were videos. A comedy-tagged video had about 156,000 likes and 6,700 collects; a sunscreen round-up had about 22,000 likes and 25,500 collects; the brand giveaway had 4,297 and 136. Collects might help distinguish reference material from entertainment in that sample, but the observation covers one keyword and date.
The old planned report used two search requests plus one detail and one comments request for each of five selected notes: 12 calls, or 13 with keyword suggestions, before any retry. That is historical call accounting, not today’s one-call cost estimate or a fresh verification of those additional endpoints. Three attempts at web-v3/note-detail with a token from app-v2 search returned HTTP 503 wrapping upstream 400 in the old session. No token-based fallback is recommended here.
FAQ
Do I need a Xiaohongshu login? These two current request schemas use SandBase API authentication and do not ask for a Xiaohongshu login cookie. This does not provide access to private or account-gated content.
Can I use a share link for comments?
The comments reference accepts share_text as an alternative. This helper intentionally validates a known note_id only; a share-link path was not tested in this update.
Why does search not require success: true?
The current published search sample has no success field. Requiring it would reject that sample. The helper checks integer code: 0, validates the relevant list and rejects an explicit contradictory success value.
Can the agent keep paging or open the best note? That is a separate workflow. First inspect a complete live response, decide how to select a note and set a request budget. Do not treat the historic code or trimmed cursor as a verified implementation.
Can I use this for a market ranking? A sampled page can start a research question. It is not a representative market dataset; missing metrics, ads, changing results and an unverified view count all affect comparisons.
Choose the first request that matches the input you already have. Keep its returned sample and limitations together before expanding the research task.
For a 2026 pricing comparison of the live SandBase Xiaohongshu hub, see Best Xiaohongshu API in 2026: Pricing Compared.
Found this useful? Share it