Skip to navigation

How do I turn a shared Xiaohongshu link into useful note and comment research?

To research a shared Xiaohongshu note, pass the original link as share_text to the App action that matches the task. To read the description, use xiaohongshu.app_v2.get_image_note_detail or xiaohongshu.app_v2.get_video_note_detail; to read the discussion, request the note’s top-level comments with xiaohongshu.app_v2.get_note_comments. When you already have a verified note identifier, pass note_id instead.

For example, a teammate shares a coffee machine cleaning tutorial and asks where users get stuck. If you have already read the tutorial, go straight to the comments and keep the exact questions and the machine models commenters mention. Fetch the note detail only when you need to check what the tutorial says.

Existing materialNext step
A note link on xiaohongshu.com, or an xhslink.com / xhslink.cn share linkUse share_text for the selected App action
note.id in saved search resultsReuse it as note_id
The note identifier after /explore/ or /discovery/item/Preserve it as text for note_id
A profile link, user ID or account handleStart account research, then select a note for comment research

The suffix of a short link is not the note identifier. Note IDs and user IDs can look similar, so check which kind of page supplied the value. Keep the query parameters with the original link; you do not need to generate an access token.

Choose by what you want to accomplish

TaskActionLocator
Read an image note’s description and image informationxiaohongshu.app_v2.get_image_note_detailshare_text or note_id
Read a video note’s description and detailsxiaohongshu.app_v2.get_video_note_detailshare_text or note_id
Find questions and experiences in its commentsxiaohongshu.app_v2.get_note_commentsshare_text or note_id

Supply one locator for the intended note: the verified note ID when you have one, otherwise the share link. When you know the note type, choose the matching detail action. A description is text only: the detail actions do not read image content or transcribe video, so supply images or transcripts separately when the task needs them.

For example, replace <note_share_link> with the real link to retrieve image-note details:

curl -sS https://api.beatapi.io/v1/social-data/call \
-H "Authorization: Bearer $BEATAPI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"action":"xiaohongshu.app_v2.get_image_note_detail","params":{"share_text":"<note_share_link>"}}' \
-o xiaohongshu-note.json

How do you use the result?

  1. Confirm the note. Image details are under data.data[].note_list[] and video details under data.data[]. Match the title, author and original link, then save the intended note’s id. If several notes appear, select the matching note object.
  2. Keep a source you can revisit. Record the original link, confirmed note ID, query time and request_id. Join later observations by note ID while preserving the share link as a source.
  3. Read comments against your question. A comment’s note_id identifies the note, and the comment’s id identifies the comment itself. Record “exact excerpt—step or condition—answer needed” instead of counting words such as cleaning or difficult.
  4. Read replies where context matters. A reply request with xiaohongshu.app_v2.get_note_sub_comments takes the root comment’s id as comment_id. A reply’s target_comment.id can point to another reply, so keep the thread context. Continue to further pages with the returned cursor.

“Does this brush work with every model?” is a compatibility question. “My machine skips that step” is an experience with one particular machine: keep the wording and context before interpreting the comment. When excerpts are missing or the target note does not match, collect more material before drawing conclusions. For exports, follow the comment research guide.

To hand the task to an assistant with the tools configured, use a prompt such as:

Research the coffee-machine cleaning tutorial behind this link. Reuse saved descriptions and prioritize comments. Identify confusing steps, usage conditions and unanswered questions. Attach original excerpts, their note and relevant replies. State what was read, then identify discussions worth expanding.

Why does another action require xsec_token?

App and Web detail actions take different inputs. The three App actions above need no separate xsec_token; xiaohongshu.web_v3.fetch_note_detail requires both note_id and xsec_token. Pass the inputs that the chosen action declares.

X-S, X-T and x-S-Common are signing headers used by direct web clients. Note IDs, link access tokens and the BeatAPI key each serve a separate purpose. The App actions use normal BeatAPI authentication plus their declared locators, so you need no web-signing library and no copied browser Cookie. MediaCrawler’s client source shows how MediaCrawler signs its own direct requests; MediaCrawler’s signing is not a step in this workflow.

First check that the link points to the intended note. If you have a complete note link or a verified note ID, use that instead. Otherwise save the link, the returned message and the request_id, and mark the note as unavailable. The business-error explanation covers how to handle the response.

Budget with current pricing. A comments-only task costs the comment pages; add detail requests only when you need the description, and reuse saved results.

Optional: prepare the request locally

Save prepare_note_request.py below. Choose the content type when you know it, or comments when the task is comment research. prepare_note_request.py accepts one 24-character hexadecimal note ID or one complete HTTPS URL from the listed share hosts. A long xiaohongshu.com URL must have an /explore/NOTE_ID or /discovery/item/NOTE_ID path; profile and login pages are not note targets. The helper rejects pasted share text, credentials in URLs, ports, fragments and unrelated domains. The helper is stricter than the API, which may accept other share_text formats. prepare_note_request.py makes no calls, does not resolve short links and does not check that the note exists.

import json,os,pathlib,re,sys
from urllib.parse import urlsplit
kind,locator,output=sys.argv[1:4]
actions={'image':'get_image_note_detail','video':'get_video_note_detail','comments':'get_note_comments'}
if kind not in actions:raise SystemExit('Choose image, video or comments; do not auto-try both detail actions')
if re.fullmatch(r'[0-9a-fA-F]{24}',locator):
params={'note_id':locator}
else:
try:parsed=urlsplit(locator)
except ValueError:raise SystemExit('Invalid URL')
if (parsed.scheme!='https' or parsed.hostname not in {'xiaohongshu.com','www.xiaohongshu.com','xhslink.com','www.xhslink.com','xhslink.cn','www.xhslink.cn'}
or parsed.username is not None or parsed.password is not None or parsed.fragment or not parsed.path.strip('/')
or any(c.isspace() or ord(c)<32 or ord(c)==127 for c in locator)):
raise SystemExit('Use one complete HTTPS share URL or a 24-character note ID, not copied headers or share prose')
try:
if parsed.port is not None:raise SystemExit('Do not supply an explicit port')
except ValueError:raise SystemExit('Invalid URL port')
if parsed.hostname in {'xiaohongshu.com','www.xiaohongshu.com'} and not re.fullmatch(r'/(?:explore|discovery/item)/[0-9a-fA-F]{24}/?',parsed.path):
raise SystemExit('For a long URL use an explore or discovery/item note path, not a profile or login page')
params={'share_text':locator}
os.umask(0o077)
with pathlib.Path(output).open('x',encoding='utf-8') as destination:
json.dump({'action':'xiaohongshu.app_v2.'+actions[kind],'params':params},destination,ensure_ascii=False,indent=2)
print(output)
python3 prepare_note_request.py comments '0123456789abcdef01234567' note-request.json

The ID in the example is illustrative: replace the ID with your own verified ID, or quote your actual URL as a single shell argument. A URL can contain access tokens, so keep the request file private and do not paste the file into public tickets. The new file contains only action and params, holds no API key or browser header, and is never written over an existing file. Check the chosen action and the current price, then submit the file with the usual private Bearer header:

curl -sS https://api.beatapi.io/v1/social-data/call -H "Authorization: Bearer $BEATAPI_API_KEY" -H 'Content-Type: application/json' --data-binary @note-request.json -o note-response.json

Only the curl command above makes a call; do not run the curl command with the illustrative ID. Check the returned action and the note identity with the steps above, or continue with the complete comment export workflow. A short-link suffix is still not a note ID. When content is missing, stop the batch for review instead of retrying with the other detail action.