Monitor what Xiaohongshu (RedNote) users say about a brand in Python

A developer built Qovia, an API for pulling Xiaohongshu (RedNote) brand mentions into a Python pipeline that searches notes, collects comments, appends results to CSV and summarizes them with pandas. The tutorial covers authenticated requests with a bearer key, per-call billing metadata, 429 retry handling, and search parameters such as sort order, note type and time window for recurring brand monitoring.

I build Qovia, the API used in this post. The pipeline itself search, enrich, collect comments, append to CSV, summarize works with any Xiaohongshu data source; the CSV and pandas parts are plain Python. Xiaohongshu 小红书, called RedNote outside China is where Chinese consumers post reviews, shopping hauls, "is it worth it?" comparisons and complaints. For a consumer brand that sells in China, or one thinking about it, it's one of the most direct places to hear what customers actually say, in their own words, with photos. The comment sections are often more honest than the notes themselves: that's where people ask "where did you buy it?", "mine broke after a week" or "is this an ad?". In this tutorial we'll build a small brand monitor in Python. For one brand keyword it will: You need Python 3.9+, requests and pandas : pip install requests pandas export QOVIA KEY=sk-qovia-... key from the Qovia console Get a key from Qovia https://qovia.ai/?utm source=devto&utm medium=article&utm campaign=xiaohongshu-brand-monitor-python . Requests authenticate with Authorization: Bearer <key an x-api-key header also works . The Xiaohongshu API page https://qovia.ai/xiaohongshu-api/?utm source=devto&utm medium=article&utm campaign=xiaohongshu-brand-monitor-python lists all the Xiaohongshu endpoints with a real request and response. Every response has the same envelope: the result is in data , and meta reports the charge meta.billed , meta.charged usd , meta.empty . Empty results come back as HTTP 200 with meta.empty: true and are not charged. Errors are {"error": {"code", "message", ...}} and are never charged. A 429 carries a Retry-After header, so the helper waits and retries once: python import os import time import requests BASE = "https://api.qovia.ai" HEADERS = {"Authorization": f"Bearer {os.environ 'QOVIA KEY' }"} spent = 0.0 def get path, params : global spent params = {k: v for k, v in params.items if v is not None} for attempt in range 2 : r = requests.get f"{BASE}{path}", headers=HEADERS, params=params, timeout=60 if r.status code == 429 and attempt == 0: time.sleep int r.headers.get "Retry-After", "10" continue r.raise for status body = r.json spent += float body.get "meta" or {} .get "charged usd" or 0 return body.get "data" or {} Unknown parameters are rejected with 400 invalid params , which is why the helper drops None values instead of sending them. GET /v1/raw/xiaohongshu/search takes a keyword 1 to 50 characters and returns 20 notes per page. The useful options for monitoring: sort : general relevance, the default , latest , most liked , most commented or most saved , note type : all default , video or image , note time : day , week , month or year , page : 1 to 50; stop when has more is false. For a recurring monitor, sort=latest with note time=week is a good default: you see what's new rather than the same viral notes every day. Each note has text an excerpt , author nickname , user id , metrics likes , comments , saves , shares and an extra object with source id the note ID , url , title , note type , published at , cover url , images , and for video notes video url and video dur s . BRAND = "瑞幸" Luckin Coffee; use any brand or product name def search notes keyword, sort="latest", note time="week", max pages=2 : notes, seen = , set for page no in range 1, max pages + 1 : page = get "/v1/raw/xiaohongshu/search", keyword=keyword, sort=sort, note time=note time, page=page no for n in page.get "items", : nid = n "extra" "source id" if nid not in seen: seen.add nid notes.append n if not page.get "has more" : break return notes Each page is one billed call, so max pages is also your cost cap. Deduplicating on the note ID is cheap insurance in case the feed shifts between pages. Now flatten the notes into CSV rows. We'll use one writer for all three files: python import csv from datetime import datetime, timezone from pathlib import Path NOTE FIELDS = "checked at", "keyword", "note id", "title", "note type", "author", "author id", "likes", "comments", "saves", "shares", "published at", "url", "excerpt" def now : return datetime.now timezone.utc .isoformat timespec="seconds" def note row keyword, n : ex, m, a = n.get "extra" or {}, n.get "metrics" or {}, n.get "author" or {} return { "checked at": now , "keyword": keyword, "note id": ex.get "source id" , "title": ex.get "title" , "note type": ex.get "note type" , "author": a.get "nickname" , "author id": a.get "user id" , "likes": m.get "likes" , "comments": m.get "comments" , "saves": m.get "saves" , "shares": m.get "shares" , "published at": ex.get "published at" , "url": ex.get "url" , "excerpt": n.get "text" or "" :200 .replace "\n", " " , } def append csv path, fields, rows : path = Path path new file = not path.exists with path.open "a", newline="", encoding="utf-8" as f: w = csv.DictWriter f, fieldnames=fields if new file: w.writeheader w.writerows rows Search results are enough for counting mentions, but for the notes people actually engage with you want the detail record. GET /v1/raw/xiaohongshu/note takes a note id the 24 hex characters in xiaohongshu.com/explore/<ID , which is extra.source id from search and returns the same record shape with exact like, comment, save and share counts, plus extra.topics the note's hashtags and extra.ip location . A deleted or missing note answers empty and is not charged. We rank the search hits by engagement and fetch details for the top few: python DETAIL FIELDS = NOTE FIELDS + "ip location", "topics" def engagement n : m = n.get "metrics" or {} return sum m.get k or 0 for k in "likes", "comments", "saves", "shares" def note details keyword, notes, top=10 : rows = for n in sorted notes, key=engagement, reverse=True :top : d = get "/v1/raw/xiaohongshu/note", note id=n "extra" "source id" if not d: continue deleted since the search, not charged row = note row keyword, d row "ip location" = d "extra" .get "ip location" row "topics" = "|".join d "extra" .get "topics" or rows.append row return rows topics is a list, so it's joined with | to fit in one CSV cell; pandas can split it again later. GET /v1/raw/xiaohongshu/comments takes a note id and returns first-level comments with a cursor. There are two orders, and they return different fields: sort=default : Xiaohongshu's own order pinned and popular first , about 5 per page, with like counts and the commenter's user ID. sort=latest : newest first, 10 to 15 per page, without like counts and with only the commenter's Xiaohongshu ID red id . For brand monitoring the default order is usually the better start, since the most liked comments tend to be the ones everybody else agrees with. Each comment has cid , text , likes , reply count , ip location , created at , images and author ; the page has cursor , has more and total . Pass cursor back unchanged for the next page: COMMENT FIELDS = "checked at", "keyword", "note id", "note title", "cid", "text", "likes", "reply count", "ip location", "created at" def comment rows keyword, detail rows, pages per note=2 : rows = for note in detail rows: cursor = None for in range pages per note : page = get "/v1/raw/xiaohongshu/comments", note id=note "note id" , sort="default", cursor=cursor for c in page.get "items", : rows.append { "checked at": now , "keyword": keyword, "note id": note "note id" , "note title": note "title" , "cid": c "cid" , "text": c.get "text" or "" .replace "\n", " " , "likes": c.get "likes" , "reply count": c.get "reply count" , "ip location": c.get "ip location" , "created at": c.get "created at" , } if not page.get "has more" : break cursor = page.get "cursor" return rows If a comment has a large reply count , GET /v1/raw/xiaohongshu/comment replies with the note id and comment id=<cid returns the thread under it oldest first, about 5 per page, same cursor rules . Each reply has parent cid and reply to cid , so you can rebuild the conversation. I left it out of the main loop to keep the call count predictable. python def run keyword=BRAND : notes = search notes keyword, sort="latest", note time="week", max pages=2 append csv "xhs notes.csv", NOTE FIELDS, note row keyword, n for n in notes details = note details keyword, notes, top=10 append csv "xhs note details.csv", DETAIL FIELDS, details comments = comment rows keyword, details, pages per note=2 append csv "xhs comments.csv", COMMENT FIELDS, comments print f"{len notes } notes, {len details } details, {len comments } comments" print f"spent this run: ${spent:.4f}" if name == " main ": run Run it once a day from cron and the CSVs become a running log of the brand on Xiaohongshu: 0 9 cd /path/to/monitor && QOVIA KEY=sk-qovia-... python3 xhs monitor.py monitor.log 2 &1 Output looks something like this illustrative, not real data : 40 notes, 10 details, 96 comments spent this run: $0.1600 python import pandas as pd notes = pd.read csv "xhs notes.csv", dtype={"note id": str} details = pd.read csv "xhs note details.csv", dtype={"note id": str} comments = pd.read csv "xhs comments.csv", dtype={"note id": str, "cid": str} notes = notes.drop duplicates "note id", keep="last" notes "day" = pd.to datetime notes "published at" , utc=True .dt.tz convert "Asia/Shanghai" .dt.date print "New notes per day:" print notes.groupby "day" .size .tail 14 latest = details.sort values "checked at" .drop duplicates "note id", keep="last" print "\nMost engaged notes:" print latest.sort values "likes", ascending=False "likes", "comments", "saves", "title", "url" .head 10 print "\nTop hashtags on those notes:" print latest "topics" .dropna .str.split "|" .explode .value counts .head 10 c = comments.drop duplicates "cid", keep="last" print "\nWhere commenters are IP location :" print c "ip location" .value counts .head 10 print "\nMost liked comments:" print c.sort values "likes", ascending=False "likes", "text" .head 10 A crude signal, not sentiment analysis: count comments containing a few words. WATCH = {"好喝": "tastes good", "难喝": "tastes bad", "贵": "expensive", "排队": "queue", "退款": "refund", "广告": "ad?"} print "\nComments mentioning:" for word, label in WATCH.items : print f" {word} {label} : {c 'text' .fillna '' .str.contains word, regex=False .sum }" The word list is the part you'll want to tune for your brand: product names, competitor names, and the complaint words that matter in your category. Because every run appends with a checked at timestamp, you can also compare a note's likes and comments across days to see which posts are still growing. If you'd rather ask questions than maintain a script, the same endpoints are available through Qovia's MCP server at https://api.qovia.ai/mcp Streamable HTTP, same API key in an Authorization: Bearer header, same billing as the HTTP API . In Claude Code: claude mcp add --transport http qovia https://api.qovia.ai/mcp \ --header "Authorization: Bearer $QOVIA KEY" Then ask something like "search Xiaohongshu for 瑞幸 notes from this week, open the five most liked, and summarize what the comments complain about." Configs for Cursor, VS Code and Claude Desktop are in the MCP docs https://qovia.ai/docs/mcp/?utm source=devto&utm medium=article&utm campaign=xiaohongshu-brand-monitor-python , and the Xiaohongshu MCP page https://qovia.ai/mcp/xiaohongshu/?utm source=devto&utm medium=article&utm campaign=xiaohongshu-brand-monitor-python lists the Xiaohongshu tools. The assistant is good for one-off digging; the script is better when you want the same numbers every day. Every Xiaohongshu endpoint used here search , note , comments , comment replies is a fixed $0.005 per successful call $5 per 1,000 . Empty results and errors are not charged. As a rough example arithmetic only : one run above is up to 2 search pages, 10 note details and up to 20 comment pages, so at most 32 calls, about $0.16. Daily for one brand, that's under $5 a month. The spent counter prints the real number each run. New accounts get 50 trial calls, counted only when a call returns data; after that it's a prepaid balance with no monthly fee. Details are on the pricing page https://qovia.ai/pricing/?utm source=devto&utm medium=article&utm campaign=xiaohongshu-brand-monitor-python , and every parameter is in the API docs https://qovia.ai/docs/?utm source=devto&utm medium=article&utm campaign=xiaohongshu-brand-monitor-python . The default rate limit is 60 requests per minute per account, more than enough for a job like this. text in search results is an excerpt. pages per note . If you build on this, tell me in the comments which brand signals you'd want added. This article was written with the help of AI.