> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

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

> Start with an existing link or note ID, choose reading or comments, keep sources and distinguish access tokens from web signatures.

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.

## Where does your link or identifier belong?

| Existing material                                                               | Next step                                                       |
| ------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| A note link on `xiaohongshu.com`, or an `xhslink.com` / `xhslink.cn` share link | Use `share_text` for the selected App action                    |
| `note.id` in saved search results                                               | Reuse 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 handle                                       | Start 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

| Task                                                   | Action                                     | Locator                   |
| ------------------------------------------------------ | ------------------------------------------ | ------------------------- |
| Read an image note's description and image information | `xiaohongshu.app_v2.get_image_note_detail` | `share_text` or `note_id` |
| Read a video note's description and details            | `xiaohongshu.app_v2.get_video_note_detail` | `share_text` or `note_id` |
| Find questions and experiences in its comments         | `xiaohongshu.app_v2.get_note_comments`     | `share_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:

```bash
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](/guides/xiaohongshu-note-comments).

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](https://github.com/NanmiCoder/MediaCrawler/blob/main/media_platform/xhs/client.py) shows how MediaCrawler signs its own direct requests; MediaCrawler's signing is not a step in this workflow.

## What if the link cannot be read?

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](/faq/xiaohongshu-business-errors) covers how to handle the response.

Budget with current [pricing](https://beatapi.io/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.

```python
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)
```

```bash
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:

```bash
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](/guides/xiaohongshu-note-comments). 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.