ナビゲーションにスキップ

Can people find my new Xiaohongshu note under its target keywords?

To check whether people can find a new note under its target keywords, pair each keyword with known note IDs, search each keyword with xiaohongshu.app_v2.search_notes, and match the note IDs in the returned results. Record each match’s position, then follow whether the note keeps appearing for the keyword and how the observed position changes over time.

For example, a brand publishes three coffee-machine tutorials intended for “coffee machine cleaning”, “steam wand cleaning” and “coffee machine descaling”. Pair each note with the relevant terms: one note can target several terms, and several notes can be observed for one term. Reuse note IDs from publishing records, links or saved search results; locating the IDs needs no extra detail query.

What will the observation help you decide?

ObservationHow to use it
A target appears in the scanned resultsRecord its position and see whether nearby results address the same question
Comparable observations move forward or backwardLook for a repeated pattern, then review content and actual business outcomes
A target is absent from the scanned pagesKeep keyword and depth, then decide whether the plan warrants deeper reading or a relevance review
A target appears only after a sort or filter changeStore the result as a separate observation and compare matching conditions first

Position means the order returned by this API observation. Different times and different App users can see different results. Record absence as an explicit state so later observations stay comparable.

How do you collect comparable records?

  1. Fix keyword, note IDs, sort and filters. Use sort_type: general for xiaohongshu.app_v2.search_notes; comment_descending addresses a different ordering.
  2. Choose a time window and depth, such as a similar time each day and one initial page per keyword. Save the actual time, inputs and responses as described in the search guide. Configure scheduled runs in your own task environment.
  3. Match targets at data.data.items[].note.id. Some items are not notes, so keep raw page positions and note-item positions separately instead of treating every page as twenty notes.
  4. For greater depth, use returned data.next_page with the first response’s data.search_id and data.search_session_id. Start each independent observation at page one.

For example, comparable note-slot positions of 12, 9 and 8 mark a term worth watching. A position of 8 followed by absence from one scanned page gives two states, not a fall to rank zero. To investigate an explanation, read the target note and the nearby content; position records alone do not show that an edited title caused a change.

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

Observe these keyword–note pairs with consistent general ordering and filters, initially one page per term. Retain actual time, query conditions, found positions and absence states. Compare matching historical records and identify terms worth following. Explain why more pages or content reading would help before expanding.

The script track_positions.py below reuses saved responses to build an observation table and adjacent-run comparisons. Collection and local analysis stay separate, so you can analyze saved results repeatedly.

Prepare the saved runs and target list

Create rank-input.json next to the saved responses, and replace the illustrative keyword, IDs, filenames and times. Each keyword can have several target notes, and one input file can hold several keyword keys. Supply at least one saved run for every keyword. Add a later run only after you have actually collected the run; track_positions.py does not schedule, search or retry.

{
"targets": {"example keyword": ["<known-note-id>", "<another-known-note-id>"]},
"runs": [
{"pages": [{"file":"day-one.json","collected_at":"2026-11-16T10:00:00Z","params":{"keyword":"example keyword","sort_type":"general","page":1}}]},
{"pages": [{"file":"day-two.json","collected_at":"2026-11-17T10:00:00Z","params":{"keyword":"example keyword","sort_type":"general","page":1}}]}
]
}

For a multi-page run, append page entries to the same pages array, using the observed next page and the original session inputs. track_positions.py rejects page gaps, changed sessions, mismatched response pages, duplicate request IDs and changed query or filter parameters. An omitted default and an explicit default count as different inputs, so record the same complete parameter set for every run.

Save as track_positions.py, then run this offline command:

python3 track_positions.py rank-input.json rank-review
import csv, datetime, hashlib, json, pathlib, sys
manifest = pathlib.Path(sys.argv[1]); manifest_bytes = manifest.read_bytes()
config = json.loads(manifest_bytes)
targets, runs = config['targets'], config['runs']
if not isinstance(targets, dict) or not targets or not isinstance(runs,list) or not runs: raise ValueError('Targets and saved runs required')
for keyword, ids in targets.items():
if not keyword.strip() or not isinstance(ids,list) or not ids or any(not isinstance(x,str) or not x.strip() for x in ids) or len(ids)!=len(set(ids)): raise ValueError('Each keyword needs unique original note IDs')
def stamp(value):
d=datetime.datetime.fromisoformat(value.replace('Z','+00:00'))
if d.utcoffset() is None: raise ValueError('Record actual query time with timezone')
return d
rows, archives, sources, scopes, moments, request_ids = [], [], [], {}, set(), set()
for run in runs:
pages=run['pages']
if not isinstance(pages,list) or not pages: raise ValueError('Saved pages required')
first=pages[0]['params']; keyword=first.get('keyword')
if keyword not in targets: raise ValueError('No targets for this keyword')
scope={k:v for k,v in first.items() if k not in ('page','search_id','search_session_id')}
if keyword in scopes and scopes[keyword]!=scope: raise ValueError('Use identical explicit query/filter parameters across observations')
scopes[keyword]=scope
observed=pages[0]['collected_at']; moment=stamp(observed)
if (keyword,moment) in moments: raise ValueError('Duplicate observation time for keyword')
moments.add((keyword,moment))
found, note_slot, total_items, next_page, session, last_time, seen, can_continue = {}, 0, 0, 1, None, None, set(), True
for page in pages:
params=page['params']; number=params.get('page')
if not can_continue: raise ValueError('Do not extend an empty/repeated page')
if type(number) is not int or number!=next_page: raise ValueError('Start at page one and follow the observed next_page without gaps')
if {k:v for k,v in params.items() if k not in ('page','search_id','search_session_id')}!=scope: raise ValueError('Mixed query/filter run')
time=stamp(page['collected_at'])
if last_time is not None and time<last_time: raise ValueError('Page collection times go backwards')
last_time=time
raw=(manifest.parent/page['file']).read_bytes(); response=json.loads(raw); rid=response.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 response.get('status')!='succeeded' or response.get('error') is not None or response.get('action')!='xiaohongshu.app_v2.search_notes': raise ValueError('Failed or mismatched search')
body=response['data']
if body.get('success') is not True or type(body.get('code')) is not int or body['code']!=0 or type(body.get('page')) is not int or body['page']!=number: raise ValueError('Wrong page or business error')
returned=(body.get('search_id'),body.get('search_session_id'))
if any(not isinstance(x,str) or not x.strip() for x in returned): raise ValueError('Missing session identity')
if session is None:
if params.get('search_id') not in (None,'') or params.get('search_session_id') not in (None,''): raise ValueError('Start a fresh page-one observation without prior session IDs')
session=returned
elif returned!=session or (params.get('search_id'),params.get('search_session_id'))!=session: raise ValueError('Changed search session')
items=body['data']['items']
if not isinstance(items,list): raise ValueError('Missing result items')
name='raw-'+str(len(archives)+1).zfill(3)+'.json';digest=hashlib.sha256(raw).hexdigest();archives.append((name,raw))
sources.append({'file':name,'sha256':digest,'request_id':rid,'keyword':keyword,'page':number,'collected_at':page['collected_at']})
fresh=0
for position,item in enumerate(items,1):
if not isinstance(item,dict): raise ValueError('Invalid result item')
note=item.get('note')
if note is None: continue
if not isinstance(note,dict): raise ValueError('Unreadable note object; do not report it as not found')
nid=note.get('id')
if not isinstance(nid,str) or not nid.strip(): raise ValueError('Missing note ID')
note_slot+=1
if nid not in seen: fresh+=1;seen.add(nid)
if nid in targets[keyword] and nid not in found:
found[nid]={'page':number,'item_position_on_page':position,'note_slot_in_saved_run':note_slot,
'request_id':rid,'source_file':name,'source_sha256':digest}
total_items+=len(items);can_continue=fresh>0
next_page=body.get('next_page')
if next_page is not None and (type(next_page) is not int or next_page<=number): next_page=None
for nid in targets[keyword]:
row={'keyword':keyword,'note_id':nid,'observed_at':observed,'last_page_at':pages[-1]['collected_at'],
'pages_scanned':len(pages),'items_scanned':total_items,'note_slots_scanned':note_slot,'unique_notes_scanned':len(seen),
'state':'found' if nid in found else 'not_found_in_scanned_pages','scope':scope,
'page':None,'item_position_on_page':None,'note_slot_in_saved_run':None,
'continuation_available':can_continue and next_page is not None,'request_id':None,'source_file':None,'source_sha256':None}
row.update(found.get(nid,{}));rows.append(row)
missing=set(targets)-{row['keyword'] for row in rows}
if missing: raise ValueError('Every target keyword needs at least one saved run')
rows.sort(key=lambda r:(r['keyword'],r['note_id'],stamp(r['observed_at'])))
previous={};changes=[]
for row in rows:
key=(row['keyword'],row['note_id']);before=previous.get(key)
if before:
both=before['state']=='found' and row['state']=='found'
changes.append({'keyword':key[0],'note_id':key[1],'before':before['observed_at'],'after':row['observed_at'],
'before_state':before['state'],'after_state':row['state'],
'observed_note_slots_up':before['note_slot_in_saved_run']-row['note_slot_in_saved_run'] if both else None,
'equal_pages_scanned':before['pages_scanned']==row['pages_scanned'],
'scope':'Change in saved API ordering only; not universal app ranking or causal SEO impact'})
previous[key]=row
out=pathlib.Path(sys.argv[2]);out.mkdir()
for name,raw in archives:(out/name).write_bytes(raw)
(out/'input-manifest.json').write_bytes(manifest_bytes)
for name,value in [('observations.json',rows),('changes.json',changes),('coverage.json',{'sources':sources,
'manifest_sha256':hashlib.sha256(manifest_bytes).hexdigest(),'saved_runs':len(runs),'executed_calls':0,
'position_definition':'Raw item position on page and note slots across consecutive saved pages; repeated notes occupy slots; first appearance retained'})]:
(out/name).write_text(json.dumps(value,ensure_ascii=False,indent=2),encoding='utf-8')
fields=['keyword','note_id','observed_at','state','page','item_position_on_page','note_slot_in_saved_run','pages_scanned','items_scanned','unique_notes_scanned','continuation_available','request_id','source_file','source_sha256']
with (out/'observations.csv').open('w',encoding='utf-8-sig',newline='') as f:
writer=csv.DictWriter(f,fieldnames=fields);writer.writeheader()
for row in rows:
cells={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 cells.items()})
print(json.dumps({'saved_runs':len(runs),'target_observations':len(rows),'comparisons':len(changes),'executed_calls':0}))

Read the deliverables correctly

  • observations.csv / .json: one row per target note and saved observation. item_position_on_page counts every returned item; note_slot_in_saved_run counts note-bearing slots across the consecutive saved pages. Non-note items do not count as note slots; repeated notes still occupy slots, and the target’s first appearance is kept. The two coordinates are documented observation positions, not a normalized site-wide rank.
  • state: not_found_in_scanned_pages: the position fields stay empty, and the row still reports the pages, items and unique notes scanned. The state does not set a lower bound for every user and does not prove that the note is gone.
  • changes.json: compares adjacent saved observations for the same keyword and note. A positive observed_note_slots_up means an earlier position in these returned note slots. If either observation did not find the note, the change is null, not a jump from zero. Different page depths are explicitly marked. Identical settings do not eliminate personalization or changing platform results.
  • coverage.json, input-manifest.json and raw-*.json: original response bytes, request IDs, recorded page times and hashes. A collection spans the first to the last page time, not one atomic instant. The hashes check local integrity; the hashes do not authenticate query parameters on the server or prove an App-visible ranking. Keep full responses private.

A weekly report can read: “Camping coffee, general order, one page per check. The note appeared in slot 8 on Monday and slot 5 on Wednesday.” If the note is missing from Friday’s first page, record “Not found on page one” and leave the change blank. To explain a difference, review the neighboring notes and what changed between checks.

What does the observation cost?

track_positions.py makes zero calls. The cost of new collection is the number of keyword observations times the pages actually requested, multiplied by the current search price on the pricing page. Thirty keywords once daily, one page each, is 210 calls per week; a second page every time doubles the call budget. A page does not hold a fixed number of notes, and checking several target IDs in one saved response needs no separate calls. Do not add detail or comment calls just to determine position.

Sources: one previously paid search page, replayed locally with a returned target and a deliberately absent synthetic ID, produced found and not-found rows without a new request; that page used comment sorting, not general sorting. Multi-page and two-time-point comparisons were tested with synthetic fixtures. For ongoing monitoring, set up your own collection schedule with a budget; this page creates no automation.