> 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 find useful Xiaohongshu posts for my next content brief?

> Start with a specific content question, screen one page of results, retrieve detail descriptions only for selected posts, and deliver a table with clear selection reasons.

To find useful Xiaohongshu posts for a content brief, search one page for a specific keyword with `xiaohongshu.app_v2.search_notes`, shortlist the relevant notes, and fetch details only for the notes you want to read. For a beginner’s guide to camping coffee, start with “camping coffee” and look for questions about gear, brewing and packing.

The result is a research table with titles, engagement and your selection reasons. Label each item you have seen only in search as a search excerpt.

If you already have particular notes, use the [link and ID workflow](/faq/xiaohongshu-share-links) instead of paying for a search to rediscover the notes. If your question is what people complain about, search only finds the sample; you also need to [read comments and replies](/guides/xiaohongshu-note-comments).

## What will I hand to my teammate?

The handover is a usable `notes.csv`, not a pile of JSON: titles, authors, search excerpts, likes/saves/comments/shares, note IDs and two review fields, `selected` and `selection_reason`. You fill the two review fields; the script does not decide relevance or invent a viral-content score.

The table below is an **illustration of how to review results**; the rows are not findings from a search:

| What you encounter                                          | Review decision                                                     | Next question                                                           |
| ----------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| A title about brewing at a campsite matches the brief       | Keep the post and say which method or explanation you want to study | Retrieve detail descriptions if the excerpt cannot establish the steps. |
| A popular cafe check-in is unrelated to beginner camping    | Do not select the check-in just because its numbers are high        | Skip the check-in's detail-call cost in this round.                     |
| Many comments, but the title does not reveal the discussion | Treat the post as a discussion sample, not proof of a need          | Read the comments before deciding what people are asking.               |

Add a short handover note: what you searched, which posts deserve reading, why each post was selected and what remains to investigate. Saves are not purchases, comment totals are not unique people, and search position is not a quality ranking.

## 1. Narrow the question before choosing the keyword

If “coffee” is too broad, first write the goal in one sentence, such as helping a first-time camper prepare coffee. Use `露营咖啡` (camping coffee) for the first round. If results drift away from the brief, start a separate search with a better term; do not combine different queries and filters into one ranking.

If you need recent posts, videos only or examples with more saves or comments, choose [time, type and sorting](/faq/xiaohongshu-search-filters) first. The starting example supplies only a keyword, so the example does not collect every highly saved post from the past week.

## 2. Use the first page to check the keyword

Read the titles and excerpts on the first page. If most results are café visits, start a separate search for beginner pour-over at a campsite. If the results already include relevant tutorials but you need a low-budget or lightweight setup, request another page or try a more specific term.

With [BeatAPI MCP](https://beatapi.io/mcp) already connected, give your assistant this brief:

> Search the first page for 露营咖啡 (camping coffee). List the title, author, note ID, search excerpt and engagement. Group candidates by gear checklist, brewing steps or cleanup and packing. Stop at page one and list notes worth a detail or comment lookup separately.

The MCP tool preview shows the first five items. Read the saved result for the request before deciding whether to fetch another page.

## 3. Export the table and explain why each source matters

Create `notes.csv` with the local exporter below. Screen each note for relevance before using engagement as a clue, then fill `selected` and `selection_reason`. “Study how the post explains beginner equipment choices” is more actionable than “many likes.”

Repeated notes are deduplicated by ID, not by title. The table keeps authors and collection sources for review; the table does not generate working note-share links. To revisit a post, find the post by title, author and ID on the author's account. If you cannot locate the post, mark the row unresolved instead of inventing a link without the required access token.

## 4. Retrieve details only for the posts worth studying

Choose the notes you want to read and put each returned detail description in `detail_text`. Keep `search_excerpt` for rows that have search text only. Mark the reading status after review, and open the original post when you need text from images.

Call the image detail action for a known image post and the video detail action for a known video post. Do not try both actions automatically to discover the type. Match the returned note by the selected ID, not by position in a result list. A video's description is not a spoken transcript.

After reading, decide whether to keep the angle, find a different approach or investigate the discussion. To investigate the discussion, follow the [comment-research workflow](/guides/xiaohongshu-note-comments). A comment count alone cannot establish user needs. Study the questions and structure; do not copy someone else's text as your own draft.

## 5. Keep the budget and research scope clear

Searching P pages and retrieving details for N selected notes takes P + N platform calls. Comment and model calls count separately; see [BeatAPI pricing](https://beatapi.io/pricing). Edit, filter and re-export from the files you saved.

Stop at the approved page limit, an error, a repeated full page, missing next-page information or an abnormal state. Record the keyword, filters, date and actual pages beside the table. The table represents the collected sample, not every matching post on the platform or a stable ranking. Repeated observations of a known note belong in the [search-position workflow](/faq/xiaohongshu-search-positions).

## Implementation: check current capabilities and prices

You need a BeatAPI API key. Search and Inspect are free; execution spends your balance. The steps below use HTTP. If MCP already ran the same search, do not buy the same page again just to export it.

```bash
curl -sS https://api.beatapi.io/v1/capabilities/search \
  -H "Content-Type: application/json" \
  -d '{"query":"小红书 搜索笔记"}'
```

Pass the actual reference to Inspect; the reference below is the verified action:

```bash
curl -sS https://api.beatapi.io/v1/capabilities/inspect \
  -H "Content-Type: application/json" \
  -d '{"reference":"data:xiaohongshu.app_v2.search_notes"}'
```

Check readiness, inputs and the current price. Only execute capabilities marked ready or runnable; a listed capability is not necessarily executable. If you choose Run, the request below asks for a small preview from one page:

```bash
curl -sS https://api.beatapi.io/v1/capabilities/run \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reference":"data:xiaohongshu.app_v2.search_notes","input":{"keyword":"露营咖啡"},"view":"preview","max_items":5}'
```

The Run request above is an example, not a recorded result. Read the saved result with the returned request_id under the [result-reading contract](https://docs.beatapi.io/capabilities). Preview size is not platform pagination. The fixed exporter below accepts a complete Social Data response, not an MCP preview.

## Implementation: save a search page

To use the fixed exporter on this page, call Social Data directly and save the full response. **The direct call and Run are alternative execution routes, not two calls for the same page.**

```bash
curl --fail-with-body -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.search_notes","params":{"keyword":"露营咖啡","page":1}}' \
  -o xiaohongshu-search-page-1.json
```

The first response's `data.search_id` and `data.search_session_id` sit next to data.page/data.next_page. If another page is approved, keep the first session, keyword and filters, and pass the real next-page value. The request below fetches page two:

```bash
curl --fail-with-body -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.search_notes","params":{"keyword":"露营咖啡","page":2,"search_id":"<first_search_id>","search_session_id":"<first_search_session_id>"}}' \
  -o xiaohongshu-search-page-2.json
```

Stop on empty or repeated full pages, errors or the approved limit. Paging does not promise every match. `export_notes.py` merges only one query-and-filter round; keep the raw files, and never substitute titles for IDs.

## Implementation: export the review table

Create `search-manifest.json` with each page's actual parameters, observation time and file. The example lists one page:

```json
{"pages":[{"params":{"keyword":"露营咖啡","page":1},"collected_at":"<actual_query_time>","file":"xiaohongshu-search-page-1.json"}],"details":[]}
```

Save the script below as `export_notes.py`. The verified search path is `data.data.items[].note`. `export_notes.py` keeps search excerpts separate from later detail text and leaves the selection fields for human review. Sources: `export_notes.py` was run on an already authorized saved search page and produced 20 unique notes, with no additional paid query.

```python
import csv,json,pathlib,sys
from decimal import Decimal,InvalidOperation
manifest_path,target=map(pathlib.Path,sys.argv[1:3])
manifest=json.loads(manifest_path.read_text(encoding='utf-8'))
if not manifest.get('pages') or manifest['pages'][0]['params'].get('page')!=1:raise ValueError('Start manifest with page one')
rows,seen,session=[],set(),None
scope=None;states=[]
for page in manifest['pages']:
    params=page['params'];identity={k:v for k,v in params.items() if k not in ('page','search_id','search_session_id')}
    if scope is None:scope=identity
    if identity!=scope:raise ValueError('Do not merge different query/filter runs')
    payload=json.loads((manifest_path.parent/page['file']).read_text(encoding='utf-8'))
    if payload.get('status')!='succeeded' or payload.get('action')!='xiaohongshu.app_v2.search_notes':raise ValueError('Wrong or failed search')
    upstream=payload['data']
    if upstream.get('success') is not True or upstream.get('code')!=0:raise ValueError('Search business failure')
    if upstream['page']!=params['page']:raise ValueError('Wrong page returned')
    if session is None:session=(upstream['search_id'],upstream['search_session_id'])
    if params['page']>1 and (params.get('search_id'),params.get('search_session_id'))!=session:raise ValueError('Use first-page session')
    new=0
    for rank,item in enumerate(upstream['data']['items'],1):
        note=item.get('note')
        if not isinstance(note,dict):continue
        nid=note.get('id')
        if not isinstance(nid,str) or not nid:raise ValueError('Missing note ID')
        if nid in seen:continue
        seen.add(nid);new+=1
        row={'note_id':nid,'title':note.get('title'),'search_excerpt':note.get('desc'),
             'type':note.get('type'),'published_at_raw':note.get('timestamp'),
             'author_name':(note.get('user') or {}).get('nickname'),
             'author_id':(note.get('user') or {}).get('userid'),
             'first_seen_page':params['page'],'position_on_page':rank,
             'request_id':payload.get('request_id'),'source_file':page['file'],
             'collected_at':page['collected_at'],'selected':'','selection_reason':'',
             'detail_text':'','detail_source_file':'','detail_request_id':'','text_scope':'search_excerpt'}
        for out,key in [('likes','liked_count'),('saves','collected_count'),('comments','comments_count'),('shares','shared_count')]:
            value=note.get(key)
            if value is not None:
                if isinstance(value,bool):raise ValueError('Invalid metric')
                n=Decimal(str(value))
                if not n.is_finite() or n<0 or n!=n.to_integral_value():raise ValueError('Invalid metric')
                value=int(n)
            row[out]=value
        row['image_urls']=json.dumps([x['url'] for x in note.get('images_list',[]) if isinstance(x,dict) and isinstance(x.get('url'),str)],ensure_ascii=False)
        rows.append(row)
    states.append({'page':params['page'],'new_notes':new,'next_page':upstream.get('next_page'),
        'search_id':session[0],'search_session_id':session[1]})
    if not new:break  # Empty or repeated full page: do not continue scanning blindly.
if not rows:raise ValueError('No usable notes; do not replace an old export')
by_id={row['note_id']:row for row in rows}
review_path=sys.argv[3] if len(sys.argv)>3 else None
if review_path is not None:
    with pathlib.Path(review_path).open(encoding='utf-8-sig',newline='') as review:
        reader=csv.DictReader(review)
        if not reader.fieldnames or any(reader.fieldnames.count(k)!=1 for k in ('note_id','selected','selection_reason')):raise ValueError('Missing or duplicate review columns')
        reviewed=set()
        for entry in reader:
            nid=entry['note_id']
            if nid not in by_id or nid in reviewed:raise ValueError('Unknown or duplicate reviewed note ID')
            selected,reason=entry['selected'],entry['selection_reason']
            if selected not in ('','yes','no') or not isinstance(reason,str):raise ValueError('Use blank/yes/no and a text reason')
            if selected and not reason.strip():raise ValueError('Selected or excluded notes need a reason')
            # Undo this exporter's formula guard once, then reapply on CSV output.
            if reason.startswith("'") and reason[1:].lstrip().startswith(('=','+','-','@')):reason=reason[1:]
            by_id[nid].update(selected=selected,selection_reason=reason);reviewed.add(nid)
        if reviewed!=set(by_id):raise ValueError('Review must include every candidate; do not silently drop decisions')
for detail in manifest.get('details',[]):
    nid=detail['note_id']
    if nid not in by_id:raise ValueError('Detail is outside this candidate set')
    response=json.loads((manifest_path.parent/detail['file']).read_text(encoding='utf-8'))
    if response.get('status')!='succeeded':raise ValueError('Failed detail')
    if response['data'].get('success') is False or ('code' in response['data'] and (type(response['data']['code']) is not int or response['data']['code']!=0)):raise ValueError('Detail business failure')
    action=response.get('action')
    if action=='xiaohongshu.app_v2.get_image_note_detail':notes=[n for w in response['data']['data'] for n in w.get('note_list',[])]
    elif action=='xiaohongshu.app_v2.get_video_note_detail':notes=response['data']['data']
    else:raise ValueError('Wrong detail action')
    matches=[n for n in notes if n.get('id')==nid]
    if len(matches)!=1 or not isinstance(matches[0].get('desc'),str) or not matches[0]['desc'].strip():raise ValueError('Expected one matching nonempty detail text')
    by_id[nid].update(detail_text=matches[0]['desc'],detail_source_file=detail['file'],detail_request_id=response.get('request_id'),text_scope='detail_retrieved')
def safe(value):
    if value is None:return ''
    text=str(value)
    return "'"+text if text.lstrip().startswith(('=','+','-','@')) else text
target.mkdir()
with (target/'notes.csv').open('x',encoding='utf-8-sig',newline='') as output:
    writer=csv.DictWriter(output,fieldnames=list(rows[0]));writer.writeheader()
    writer.writerows({k:safe(v) for k,v in row.items()} for row in rows)
(target/'notes.json').write_text(json.dumps(rows,ensure_ascii=False,indent=2),encoding='utf-8')
(target/'paging.json').write_text(json.dumps(states,ensure_ascii=False,indent=2),encoding='utf-8')
print(json.dumps({'unique_notes':len(rows),'details_attached':sum(r['text_scope']=='detail_retrieved' for r in rows)}))
```

```bash
python3 export_notes.py search-manifest.json note-shortlist
```

The outputs are `notes.csv`, `notes.json` and `paging.json`; an existing output directory is never overwritten. `notes.csv` is for screening, `notes.json` keeps all fields, and `paging.json` records the search state. Verified input fields include title/desc, liked_count/collected_count/comments_count/shared_count, user.nickname/user.userid and images_list\[].url. The search desc is an excerpt, not full text, standalone hashtags or views.

### Attach text for the selected items

For each selected note, call `xiaohongshu.app_v2.get_image_note_detail` for image posts or `xiaohongshu.app_v2.get_video_note_detail` for videos with `{"note_id":"<selected_note_id>"}`, and save each response separately. Do not call both actions automatically.

Add `{"note_id":"<selected_note_id>","file":"selected-detail.json"}` to manifest.details and rerun into a new directory, passing the previously reviewed CSV as the third argument:

```bash
python3 export_notes.py search-manifest.json note-shortlist-with-details note-shortlist/notes.csv
```

Fill `selected` with `yes` for selected, `no` for excluded or blank for undecided, and record the reason. Keep every original row; filter rows instead of deleting rows. Decisions and reasons are matched by note ID. Without the third argument, the review columns start blank. Empty detail text or a business failure stops the export before any output is created; the previously reviewed table stays available for correction and another offline export. `export_notes.py` matches the exact ID in image `data.data[].note_list[]` or video `data.data[]`, puts the returned description in detail_text, and keeps the detail's source and request ID. `detail_retrieved` means a nonempty description was returned; `detail_retrieved` does not certify complete text, text inside images or human review. Rows without details keep the search-excerpt scope. For other metrics, note the [difference between reads and exposures](/faq/xiaohongshu-views-impressions).

Sources: the search export was validated against a saved real response; further pages and detail matching rely on contract evidence and offline fixtures, with no new paid detail test. Empty data or errors do not automatically mean no content, and do not trigger retries. See the [Social Data contract](https://docs.beatapi.io/social-data).

For a single search with no exporter, follow the [quick Xiaohongshu search guide](/guides/search-xiaohongshu-notes).