> 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.

# What do readers care about on Xiaohongshu, and how can top comments guide research?

> Start with selected posts, use highly liked comments to choose what to read, retrieve context selectively, and report the limits of displayed location labels.

To read the Xiaohongshu comments readers care about most, call `data:xiaohongshu.app_v2.get_note_comments` with `sort_strategy:"like_count"`; the most-liked first-level comments come first. Start with one page for a note ID or share link and pick the questions worth answering. When a comment needs context, call `data:xiaohongshu.app_v2.get_note_sub_comments` with the parent comment's ID to fetch the replies.

If a highly liked comment says a step in the instructions is unclear, keep the exact wording, the note link and the instruction step the comment refers to. Group separate comments about the same issue and keep each comment's source. The [comment research workflow](/guides/xiaohongshu-note-comments) turns the grouped comments into a list of questions to answer.

## What should I check while reading?

The table shows reading examples, not findings from a collected sample:

| What you see                                          | What to do                                                                          | Whether to collect more                                                                       |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Repeated questions about one use case                 | Record a question to verify and check whether the post already answers the question | Broader claims still require relevant samples and reviewed themes.                            |
| A highly liked criticism with a correction in replies | Preserve the statement and corrective context together                              | Expand the parent thread if only some replies were included.                                  |
| Link requests, jokes or giveaway interactions         | Include or exclude according to the research purpose, recording a reason            | Popularity does not establish a pain point or purchase.                                       |
| A detailed practical problem with few likes           | Keep the comment eligible for further human review                                  | Look beyond the ranked candidates to all observed comments; a missing like count is not zero. |

Choose `like_count` ordering to read highly liked views first, or newest ordering to examine recent discussion, and label each sample with the ordering used. Ranking a saved newest-first sample locally does not produce the platform's complete top-comments list.

## When should I expand replies?

Read the replies before interpreting ambiguous references, sarcasm, quotations or qualifications. A root comment may embed only some of the replies. Retrieve more replies only for parent comments whose context matters; do not collect every thread automatically.

One approved page means one request. Each further page and each reply request is another call. Check the current price and the approved limit before continuing, and stop on errors, repeated pages or unusable pagination. If the context stays incomplete, mark the interpretation for review instead of treating the interpretation as confirmed.

## What should I hand to a teammate?

The local exporter `rank_roots.py` (below) writes `selected-roots.csv`: candidates from each note's observed sample, with exact text, likes and sources. Read `coverage.json` first: `coverage.json` reports how many root comments were observed, how many lack a like count and which pages remain uncollected. The limit of ten is a local maximum, not a guaranteed result count.

In a separate working copy, add the relevance, the keep or exclude reason, the parent thread that needs context and the next research question. These four columns are human judgments; the script does not fill them. Use `observed-roots.json` to inspect all observed comments: a comment missing from the high-like shortlist does not mean the opinion was absent.

The location labels describe the comment sample. `coverage.json` counts labels across all observed root comments, not only the selected candidates. A label count is not a count of unique people, residence or audience geography. Keep empty, null and missing labels separate; do not infer provinces, and do not distribute raw commenter details.

## Implementation: collect one page and retrieve replies

Before the first request, use Inspect on `data:xiaohongshu.app_v2.get_note_comments` and `data:xiaohongshu.app_v2.get_note_sub_comments` to check current readiness, inputs and prices.

```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_note_comments","params":{"share_text":"<note_share_link>","cursor":"","index":0,"pageArea":"UNFOLDED","sort_strategy":"like_count"}}' \
  -o xiaohongshu-hot-comments.json
```

Do not promise reliable paging with `sort_strategy: default`: the output contract warns that `default` ordering can duplicate or omit comments. `like_count` ordering puts comments with more likes first; newest ordering helps examine recent changes. Neither limited sample measures the opinions of all readers.

## How does reply pagination differ?

| Operation            | First request                                          | Next page                                                                                        |
| -------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| First-level comments | Empty `cursor`, `index: 0`, `pageArea: UNFOLDED`       | Decode the JSON string in data.data.cursor and pass the decoded `cursor`, `index` and `pageArea` |
| Replies              | Actual parent `comment_id`, empty `cursor`, `index: 1` | Decode the JSON string in data.data.cursor, then pass the decoded `cursor` and `index`           |

The reply action is `xiaohongshu.app_v2.get_note_sub_comments`. In the reply action, `comment_id` identifies the parent comment, not the note; the note is still identified with `note_id` or `share_text`. Do not copy the first-level starting index into a reply request, and do not send a whole cursor object to a string field.

Save the original first-level response, select the parent comments that need context, and only then fetch replies. Each further page or reply request is a separate call, not a free addition to the hot-comments request. In the real responses verified on 2026-11-16, both lists are at data.data.comments\[], the text is in content and the likes are in like_count. A root comment's sub_comments\[] holds some embedded replies, not necessarily all. A separate reply page can repeat the embedded replies; deduplicate by note_id plus id.

[Collect comments and replies](/guides/xiaohongshu-note-comments) · [Business errors and charges](/faq/xiaohongshu-business-errors)

Sources: the current output contract and one paid verification of two newest-sorted root pages and one reply page (25 root comments plus eight deduplicated replies, 33 comments total). The like_count sort option comes from the contract; hot sorting was not tested separately. Both observed cursor values are JSON strings, not objects to forward verbatim, and has_more=true does not mean later pages were fetched. Check current prices before running the requests, and do not promise a fixed comment count.

## Deliver a per-note shortlist and location audit from saved pages

For a request like “20 notes, ten highly liked comments each, and where the comments are labelled,” use the saved **root-comment pages**, not author-profile locations or embedded replies. Verified root comment objects expose the label directly at `data.data.comments[].ip_location`. The recorded pages contain both strings and null in `ip_location`; keep the reported label instead of translating the label into a guessed province. `ip_location` is the comment's displayed location label, not a residence, a precise IP address, a unique commenter count or an audience distribution.

The ranking step runs locally and adds no calls. Save the script below as `rank_roots.py`. Next to your raw responses, create `root-pages.json` in the same manifest format as the comment research guide, listing root pages only. Add entries for more notes or pages only after the pages are actually saved:

```json
[{"file":"comments-page-1.json","note_id":"<actual-note-id>","action":"xiaohongshu.app_v2.get_note_comments","collected_at":"2026-11-16T10:00:00Z"}]
```

```bash
python3 rank_roots.py root-pages.json hot-review 10
```

The last argument, `10`, is a **local per-note limit**, not an API page-size promise. With newest-sorted input, the shortlist is “most liked within the saved newest sample,” not the platform's global hot list. The report records the actual sorting strategy of every page. For a fresh hot-list sample, request `like_count`: one first page for each of 20 notes is 20 calls, and additional pages or replies are charged separately at the current action price. A page can return fewer rows than requested. Do not make fresh calls just to use the offline step.

```python
import collections, csv, datetime, hashlib, json, pathlib, re, sys

manifest = pathlib.Path(sys.argv[1])
manifest_bytes = manifest.read_bytes()
pages = json.loads(manifest_bytes)
limit = int(sys.argv[3])
if not 1 <= limit <= 100: raise ValueError('Limit must be 1..100 per note')
if not isinstance(pages, list) or not pages: raise ValueError('Nonempty manifest required')
rows, seen, sources, saved, request_ids = [], {}, [], [], set()
for page in pages:
    if page.get('action') != 'xiaohongshu.app_v2.get_note_comments':
        raise ValueError('Root pages only; do not mix reply pages into this manifest')
    note = page.get('note_id')
    if not isinstance(note, str) or not note.strip(): raise ValueError('Missing note ID')
    stamp = datetime.datetime.fromisoformat(page['collected_at'].replace('Z', '+00:00'))
    if stamp.tzinfo is None: raise ValueError('Collection time needs timezone')
    raw = (manifest.parent / page['file']).read_bytes()
    payload = json.loads(raw)
    rid = payload.get('request_id')
    if not isinstance(rid, str) or not rid.strip() or rid in request_ids: raise ValueError('Missing/repeated request ID')
    request_ids.add(rid)
    if payload.get('status') != 'succeeded' or payload.get('error') is not None or payload.get('action') != page['action']:
        raise ValueError('Failed/mismatched gateway response')
    body = payload.get('data')
    if not isinstance(body, dict) or body.get('success') is not True or type(body.get('code')) is not int or body['code'] != 0:
        raise ValueError('Business error')
    data = body['data']
    if not isinstance(data.get('comments'), list) or type(data.get('has_more')) is not bool:
        raise ValueError('Invalid comments/paging shape')
    sort = data.get('current_sort_strategy')
    if sort not in ('like_count', 'latest_v2', 'default'): raise ValueError('Unrecognized observed sort')
    filename = 'raw-' + str(len(saved)+1).zfill(3) + '.json'
    digest = hashlib.sha256(raw).hexdigest()
    saved.append((filename, raw))
    sources.append({'file':filename,'sha256':digest,'request_id':rid,'note_id':note,
                    'collected_at':page['collected_at'],'observed_sort':sort,'has_more':data['has_more']})
    for item in data['comments']:
        cid, text = item.get('id'), item.get('content')
        if not isinstance(cid, str) or not cid.strip() or not isinstance(text, str) or item.get('note_id') != note:
            raise ValueError('Invalid ID/text or wrong note')
        likes = item.get('like_count')
        if likes is not None:
            if type(likes) is int and 0 <= likes <= 9007199254740991: pass
            elif isinstance(likes, str) and re.fullmatch(r'[0-9]+', likes): likes = int(likes)
            else: raise ValueError('Likes require nonnegative safe integer or original digit string')
        location = item.get('ip_location')
        if location is not None and not isinstance(location, str): raise ValueError('Invalid location')
        state = 'absent' if 'ip_location' not in item else 'null' if location is None else 'empty' if not location.strip() else 'reported'
        key = (note, cid)
        if key in seen:
            if seen[key] != text: raise ValueError('Conflicting duplicate text')
            continue
        seen[key] = text
        rows.append({'note_id':note,'comment_id':cid,'text':text,'likes':likes,
                     'ip_location':location,'location_state':state,'collected_at':page['collected_at'],
                     'request_id':rid,'source_file':filename,'source_sha256':digest})
selected, coverage = [], []
for note in sorted({source['note_id'] for source in sources}):
    sample = [r for r in rows if r['note_id'] == note]
    known = sorted((r for r in sample if r['likes'] is not None),key=lambda r:(-r['likes'],r['comment_id']))
    selected.extend(dict(r, sample_rank=i+1) for i,r in enumerate(known[:limit]))
    locations = collections.Counter(r['ip_location'] for r in sample if r['location_state']=='reported')
    coverage.append({'note_id':note,'observed_roots':len(sample),'known_likes':len(known),
                     'missing_likes':len(sample)-len(known),'selected':min(limit,len(known)),
                     'location_states':dict(collections.Counter(r['location_state'] for r in sample)),
                     'location_comment_counts':[{'label':k,'comments':v} for k,v in sorted(locations.items())]})
out = pathlib.Path(sys.argv[2]); out.mkdir()
for filename, raw in saved: (out/filename).write_bytes(raw)
(out/'input-manifest.json').write_bytes(manifest_bytes)
def write(name, value): (out/name).write_text(json.dumps(value,ensure_ascii=False,indent=2),encoding='utf-8')
write('observed-roots.json', rows)
write('selected-roots.json', selected)
write('coverage.json', {'notes':coverage,'sources':sources,'limit_per_note':limit,
      'manifest_sha256':hashlib.sha256(manifest_bytes).hexdigest(),'duplicates':'first observation retained',
      'scope':'Saved root-comment sample only; embedded replies excluded; not all comments or unique people',
      'all_comments_collected':False,'executed_calls':0})
fields=['note_id','sample_rank','comment_id','text','likes','ip_location','location_state','collected_at','request_id','source_file','source_sha256']
with (out/'selected-roots.csv').open('w',encoding='utf-8-sig',newline='') as f:
    writer=csv.DictWriter(f,fieldnames=fields); writer.writeheader()
    for row in selected:
        values={k:('' if row.get(k) is None else str(row[k])) for k in fields}
        writer.writerow({k:("'"+v if v.lstrip().startswith(('=','+','-','@')) else v) for k,v in values.items()})
print(json.dumps({'notes':len(coverage),'observed_roots':len(rows),'selected_roots':len(selected),'executed_calls':0}))
```

## Check the deliverables before interpreting the shortlist

* `selected-roots.csv` is the per-note shortlist. Ties are broken by comment ID for a deterministic order; the comment ID is not another popularity signal. Zero likes stay in the ranking; a missing like count is excluded from the ranking and counted separately.
* `observed-roots.json` keeps every deduplicated root comment in the sample. For a duplicate ID, the first observation is kept with its time and metric; later observations remain in the archived raw files. Conflicting text for one ID stops the run.
* `coverage.json` counts location labels over **all observed roots**, not only the selected ten. Absent, null and empty labels are counted separately. The counts describe comments, not people, and the labels are not normalized into provinces. Embedded replies never enter the totals.
* `raw-*.json`, the hashes and `input-manifest.json` preserve provenance. A hash detects later file changes; a hash does not prove that a server response is authentic. Before writing, `rank_roots.py` rejects data for the wrong note, failed envelopes and malformed metrics, and `rank_roots.py` refuses to overwrite an existing output directory.
* CSV escaping protects formula-like text; the exact text stays in the JSON files. Review and de-identify free text before sharing. Source responses may contain author details, so keep the raw archives private.

Running `rank_roots.py` on the two newest-sorted root pages from the paid verification gave 25 distinct root comments and a ten-row sample shortlist, with no further API call. The local run verifies the workflow and the observed location field; the local run does not verify live hot ordering or complete geographic coverage. For “three main concerns,” continue with the comment guide's reviewed labels and exact evidence quotes; `rank_roots.py` does not derive themes from like counts.

For pain-point analysis, use the comment guide's freshly generated label template: each label binds the note, the comment and the raw source hash. A local evidence number such as E000001 can repeat in another export, so an evidence number alone must not carry an old theme decision into the new export. Keep the raw archive and the integrity file with the review export.