Build a Xiaohongshu (RedNote) KOL and Notes Search Agent (2026): One SandBase Key

Xiaohongshu Marketing OAuth does not shortlist a creator who never authorized your app. A second vendor MCP, or a finished Feishu watchlist, is the other door. SandBase already has the long scoring script and the long note-research script. Neither page is both loops, and neither is the Skill path.

A Xiaohongshu KOL API here means public Pugongying (PGY) creator reads. The Xiaohongshu search notes API is the second loop: a keyword, then the notes that come back. Both run on one SANDBASE_API_KEY, the same key as the model that writes the brief. Public reads only. JSON versus a scraper versus official OAuth is the social data API guide. The same two-loop shape on Douyin is the Douyin monitor. Start with one of those, then build this.

Key takeaway

• Loop A shortlists PGY creators on a campaign cadence. Loop B listens to a keyword more often. Run both when the brief should name creators and the notes that are winning.
• On 2026-11-08 the Xiaohongshu hub header read 67 of 67 endpoints. Older posts said 34 as of 2026-10-01. Treat 67 as that day’s header.
• Three PGY routes were $0.02 with no daily free-allowance sentence. xiaohongshu/app-v2/search-notes was $0.01 and its page put the call inside the shared 100 free data calls per UTC day. This article did not run inspect.
• Skill or MCP is the path inside Claude Code, Cursor, or Codex. REST reads outputs[0].data. The July scoring CSV and the note-research pager stay on their own pages.

SandBase Xiaohongshu hub — 67 of 67 endpoints for notes search, PGY creators, and public profile reads.

What you are building

Loop A names public PGY creators for a brand and a niche. Loop B names notes for a keyword that is outside that fixed list. Both are read-only. The output is a shortlist, a Markdown brief, a webhook, or all three.

Run A when the deliverable is a creator shortlist. Run B when you have keywords and no creator ids yet. A miss on search is not a failed list call.

Loop A: KOL shortlist

Pass brand_user_id, page xiaohongshu/pgy/blogger-list, then sample blogger-detail, blogger-fans-history, and one page of app-v2/user-posted-notes. Ask a model for fit. The tested CSV, including the 200-KOL budget and the 2026-10-01 runs, is Xiaohongshu KOL Screening Agent. This page does not reprint it.

On 2026-10-01 that tutorial sent a nested fans.count object and a blogger.content_tag array. The nested follower range filtered. Flat fans_number_lower / fans_number_upper were accepted and ignored. Those flat names are absent from the parameter table retrieved 2026-11-08. The table types blogger and fans as strings (“blogger attribute filters” and “fans profile filters”). The playground chip on the same page shows blogger as an object. Send the shape inspect returns. The October runs are evidence from that day, not a schema guarantee for today.

PGY blogger-list reference — $0.02 per call, required brand_user_id; this page does not show the shared free-allowance line.

Loop B: notes search

Optional xiaohongshu/web-v3/search-suggest, then xiaohongshu/app-v2/search-notes. Drop cards whose model_type is not a note before you rank likes and collects. Open image or video detail, and a first comments page, only for cards you keep. The tested script, including an October card with model_type ads and the paging caveats, is Xiaohongshu Note Research API. The search reference on 2026-11-08 still says a page can mix card types, and that a sample is not a market ranking or a sales figure.

app-v2/search-notes — $0.01, required keyword, and First 100 calls per day free (shared per organization).

Prerequisites and boundaries

You need a SandBase key for REST, or a browser sign-in if the coding agent follows the Skill. The Skill line is not a shell command, and the key does not go in chat:

set up https://www.sandbase.ai/SKILL.md

SKILL.md, version line 0.3.9 on 2026-11-08, says discovery and inspection are free, only a run spends the balance, and you should not assume every API shares the daily free allowance. Install stays in the Skill and MCP guide. The AI tools page is the same door, and it said eligible new accounts start with a $1 credit. Pricing calls the same offer “starter credits” and does not repeat the dollar figure, so confirm it before you budget it.

Pricing that day: eligible data APIs share 100 free calls per organization per day, reset at 00:00 UTC. Catalog search and reading a schema are $0. A failed call is not charged. Build is pay per call. Agent sandboxes were $0 for now, with fair-use caps, and any change is announced first. Model calls sit outside the data allowance. The homepage FAQ repeats the 100-call pool and says model calls are separate. SandBase does not own Xiaohongshu.

The blogger-list FAQ, retrieved 2026-11-08, says you do not apply for a separate Xiaohongshu developer key to call that SandBase route. The official docs center at https://ad-market.xiaohongshu.com/docs-center?articleId=3181 returned HTTP 200 the same day as an HTML shell with no article body in the fetch, so this page does not quote scopes from it. Cookie login, device automation, and private-message routes are the wrong default for this research.

Resolve ids and keywords

brand_user_id is the brand account the PGY list matches under. The July tutorial used 59ae4dfc5e87e72475fb3bf3 and identified it as the public Perfect Diary account. The playground chip on 2026-11-08 still pairs that id with a beauty content tag. The README sample on the same page uses 5dcfa5370000000001006030 and does not name the account. This article did not resolve either id.

The response-field table documents data.kols[], fansNum, 30-day growth, content tags, estimated CPM, and businessNoteCount. Sample JSON on that page also contains userId. The field-table rows checked today do not list it. The July runs read kols[].userId and passed it onward. Chain detail calls only after your own payload shows the id.

note_id for detail and comments is data.items[].note.id on the search reference. The same table says note.type is normal (image) or video. data.items[].note.xsec_token is described as a token observed on the card. The selected app-v2/note-comments schema does not declare that input. Do not send it, and do not treat it as the SandBase key.

With only a display name, xiaohongshu/app-v2/search-users takes keyword, at $0.01, with the free-allowance sentence. Optional form fields are page, search_id, and source. This article did not call it. Shorter hub paths such as search-note and hot-search are siblings. This loop uses the versioned ids below.

Call the Xiaohongshu KOL API and the search notes API

Catalog pages show a GET listing. Calls use the Model API:

POST https://api.sandbase.ai/v1/api/<vendor>/<path>

The body is that endpoint’s parameters only. A completed call puts the business payload on outputs[0].data. If status is not completed, or that field is missing, fail the cycle. A run id is not the payload. The helper below is the documented envelope. It was not executed for this article. No API key was available in this writing environment, and none was requested.

import os
import requests

def call_api(model: str, params: dict) -> dict:
    response = requests.post(
        f"https://api.sandbase.ai/v1/api/{model}",
        headers={
            "Authorization": f"Bearer {os.environ['SANDBASE_API_KEY']}",
            "Content-Type": "application/json",
        },
        json=params,
        timeout=90,
    )
    response.raise_for_status()
    body = response.json()
    outputs = body.get("outputs") or []
    if body.get("status") != "completed" or not outputs or outputs[0].get("data") is None:
        raise RuntimeError(
            f"SandBase call did not complete: {body.get('status')} {body.get('error')}"
        )
    return outputs[0]["data"]

Path 1: Skill or MCP

Paste the Skill line, finish the browser sign-in, and start a new session so the tools load. Then ask for a bounded cycle:

Discover a Xiaohongshu PGY blogger list tool and a Xiaohongshu search notes tool.
Inspect each one. Read the price and whether it shares the daily free data allowance.
Do not run anything until I confirm.
Then run one blogger-list page for this brand_user_id, page_num 1, page_size 5.
Then run one search-notes call for this keyword, page 1, with empty search_id and search_session_id.
Summarize creators and note cards. Do not invent fields that were not in the output.

sandbase_discover and sandbase_inspect are the free steps. sandbase_run is the paid one. Inspect before every new endpoint, including ones this page names, because a reference and a later inspect can diverge. The Skill guide covers client ids, connect, and the raw MCP URL. This page does not.

Path 2: REST

These ids were live on 2026-11-08. Prices are the reference pages that day. Re-open the page before you scale. “Free sentence” means the page showed “First 100 calls per day free (shared per organization)” and the FAQ named that endpoint inside the shared pool. “No free sentence” means the FAQ said the call is billed from the balance and the free-allowance strip was absent. That is the page, not an inspect payload.

xiaohongshu/pgy-v2/blogger-v2 is a different creator search: $0.071429 on 2026-11-08, 52 optional fields, and the same “billed from your balance” FAQ with no free sentence. It is not a cheaper alias of pgy/blogger-list.

The catalog map is Xiaohongshu (RED) Public Data API on SandBase. The Weibo-plus-Xiaohongshu launch note is Weibo and Xiaohongshu data APIs.

A first cycle, not executed here. page_size: 5 is a small sample, not a maximum. Store the raw data. The beauty tag below is the playground chip’s shape, inside code because the parameter table still types blogger as a string. Confirm before you send it.

# Not executed on this page. Inspect price and free_quota before a real shortlist.
listed = call_api(
    "xiaohongshu/pgy/blogger-list",
    {
        "brand_user_id": brand_user_id,
        "page_num": 1,
        "page_size": 5,
        "blogger": {"content_tag": ["美妆"]},
    },
)
notes = call_api(
    "xiaohongshu/app-v2/search-notes",
    {"keyword": keyword, "page": 1, "search_id": "", "search_session_id": ""},
)

Later pages need the returned search_id and search_session_id together. The reference’s first-request guide does not revalidate that handoff, and one keyword’s ids do not belong on another keyword. Business fields inside data are observed-only. Read them with .get(). A missing count stays unknown. The model call uses the same key at https://api.sandbase.ai/v1. It should quote ids from the payload. A smooth brief with no ids is a failed cycle.

Path 3: sandbox, or a clock you already run

Use the same key for a sandbox when you want dedupe or a CSV append outside the chat. Pricing said agent sandboxes were free for now. The sandbox page is an E2B-compatible workspace per run. SDK mapping is the one-key stack and the free E2B alternative. The sandbox does not replace the Xiaohongshu calls.

The pricing FAQ says that after you build an agent you can test it, publish it as an API, or schedule it. The agents page opened here is hosted Sessions, not a cron form this article used. Until you have used that schedule, keep cron or GitHub Actions, as the July screening post does. Hosted Sessions versus OpenAI sandboxes are the OpenAI Agents API path.

Cost sketch

Arithmetic on the published pages, not a bill this article ran. The 100 free calls are shared by every eligible data API in the organization, not reserved for Xiaohongshu.

One list page is $0.02 with no free sentence. Five detail calls and five fans-history calls are another $0.20, same wording. Five user-posted-notes calls are $0.01 each and do show the free sentence, so they draw 5 of the 100 if that page stays eligible. One suggest plus four search-notes polls add 5 more eligible calls at $0.01. The sketch is $0.22 on the three PGY routes from the first call, plus 10 eligible app-v2 or web-v3 calls, if the rest of the org is quiet.

Past the allowance, each search-notes call is listed at $0.01. A 15-minute keyword poll is 96 eligible calls before any shortlist. That spends the shared pool on one term. The July 200-KOL table, about 610 data calls with the three PGY routes billed from the first call, stays on the screening tutorial. Re-price that table from today’s cards before you run it. This page does not re-derive it.

The model brief is one short completion per cycle, priced on the model card. This page does not quote a token total. Failed calls are not charged. Re-checking free_quota with inspect stays $0.

SandBase, vendor MCPs, and Xiaohongshu’s own consoles

Nobody on this list is a fake product. They sell different shapes of the same morning. Figures below are what each page showed on 2026-11-08.

DataXAPI’s Chinese agent answer said a free trial of up to 333 calls. Their token comparison is dated 2026-11-06 on that page. The AgentKey RedNote page returned a docs shell, so it is not scored.

Use SandBase when the brief and the Xiaohongshu reads share one key and a poll is acceptable. Use DataXAPI, Just One, Wellbyte, or Qovia when that surface is already the repo standard. Use Xiaohongshu’s own console for an authorized brand account. A packaged Feishu monitor wins when you want the watchlist without owning the loop. This is a fit table, not a rank.

Boundaries

Public data, best effort. The reference promises the envelope. A missing field is unknown. PGY rows are a public match under a brand_user_id, which is a different view from the brand’s logged-in Pugongying console. The July post saw interMidNum of 0 on a brand account that is not itself a PGY creator. Use kols[] as the candidate pool.

The first run has no snapshot, so every note looks new. Write the snapshot and send the brief on the second run. A second completed call is a second charge. Stay inside each platform’s terms. Leave cookies and logged-in devices out of the monitor. An ads card stays a card until model_type says otherwise. 67 of 67 was the hub header on 2026-11-08. It will move.

FAQ

How do I use a Xiaohongshu KOL API without Marketing Platform OAuth?

For public creator research, call PGY listing reads with your vendor key. The brand or agency authorization belongs to Xiaohongshu’s own consoles. On SandBase: brand_user_id into xiaohongshu/pgy/blogger-list, then detail, fans history, and one page of app-v2/user-posted-notes, then a model score. Discover and inspect are free. The July tutorial is the full CSV. On 2026-11-08 those three PGY pages were $0.02 and did not show the free-allowance sentence. Confirm with inspect before you scale.

How do I build a Xiaohongshu search notes API agent for a brand or category?

Add a loop with no fixed creator list. Optionally call xiaohongshu/web-v3/search-suggest, then xiaohongshu/app-v2/search-notes with keyword, page 1, and empty search_id and search_session_id. Later pages send both ids back. Drop non-note cards. Open detail and a comments sample only for cards you keep. The note-research tutorial is the deep script. On 2026-11-08 search-notes was $0.01 and its page included the call in the shared 100 free data calls per organization per UTC day.

When should I use SandBase instead of DataXAPI, Just One, or official Xiaohongshu APIs?

Use SandBase when the loop stays in your repo, the model shares the key, and polling is acceptable. Use DataXAPI, Just One, Wellbyte, or Qovia when their surface is already the standard. Use Xiaohongshu’s own console for an authorized brand account. Use a packaged monitor when someone else should own the clock.

What to do next

Open the Xiaohongshu hub, inspect one endpoint, and run a single list page or a single keyword search only after that page still shows the price and allowance you expect. The decision among JSON, scraping, and OAuth stays in the social data API guide. The Douyin twin is the competitor monitor. The long scoring script stays in the July KOL screening tutorial. The long search script stays in the note-research tutorial. The catalog post stays on the Xiaohongshu hub article. The coding-agent install stays in the Skill guide. The shared key, including the sandbox, stays in the one-key stack.