Xiaohongshu Product Research API: Search Cards and Known SKUs
Inspect one Xiaohongshu keyword page or selected SKU, validate nested cards, preserve raw prices, and distinguish pagination sessions from product IDs.

A Xiaohongshu product response is a page layout, not a flat product record. The first search card has both a wrapper ID and an ID inside its content; only the latter is described as the goods identifier. A detail response adds another complication: some cards contain nested cards instead of a direct content field. Flattening these differences can make valid data look missing, or send a layout identifier to the wrong endpoint.
This Xiaohongshu product research API guide prepares one keyword search or one separately selected SKU lookup. The November 8, 2026 repair uses public references, August saved examples and offline tests. It does not execute a new business request, demonstrate a search-to-detail chain or collect reviews. The original September 27 design and code remain archived for comparison.
Key takeaway
- Search begins with keyword, page 1, an empty search_id and source explore_feed; the schema has no limit input.
- A known-SKU lookup uses sku_id with source/pre_page mall_search. pre_page is context, not a page number.
- Require integer code 0 and boolean success true inside completed outputs[0].data before reading the layout.
- Keep nested cards, raw prices and variant IDs intact. A saved page is not a complete catalog, stock count or commercial recommendation.
The retained cover shows a conceptual search/product/reviews chain. Its backpack price, ratings, review text and counters are illustrative artwork, not results from the saved examples or this repair.
Choose a Xiaohongshu product research API request
| Reader task | Current reference | Selected first body |
|---|---|---|
| Inspect keyword search cards | Product search | keyword, page 1, empty search_id, source explore_feed |
| Inspect one known SKU layout | Product detail | sku_id, source mall_search, pre_page mall_search |
Search requires only keyword. Page, search_id and source are optional, with the defaults explicitly chosen here. Detail requires only sku_id; its two context strings are optional. The code’s 24-character hexadecimal SKU guard follows these references locally; the schema itself has no regex or declared length bound. A rejected local input is not evidence that the upstream API was called and rejected it.
Do not substitute a product URL, wrapper card ID or a different variant’s identifier. Keep exact strings and keep the two tasks independent. The public README describes using a goods ID for detail, but the retained search and detail examples do not establish that linkage: the detail was captured earlier, and its SKU is absent from the six search cards.
Historical search-products reference with keyword, page, search_id and source, and an empty generated data object. Its description says 20 results, but the complete saved example contains six cards; this repair does not promise a fixed page count.
Setup for an existing project or agent
An existing application can reuse its local SANDBASE_API_KEY and requests dependency. Do not paste credentials into an agent prompt or replace the project’s secret handling. An already connected agent needs the selected task and an explicit stopping point; a broad “research this category” instruction can otherwise turn one read into many downstream calls.
For a new project, provide the setup skill and Markdown quickstart. A useful request is: “Implement one OpenAI keyword search with page 1 and an empty search_id. Validate the business status, keep layout IDs separate from content IDs, and stop. Test malformed layouts offline. Do not continue pages, open app links or query every returned SKU.” For a known SKU, specify that identifier instead and choose detail deliberately.
Both selected endpoints list at $0.01 in the November 8 inspection. They are eligible for the organization-shared allowance of 100 eligible calls per day, resetting 00:00 UTC. This is not a separate allowance for each endpoint or a reading of your remaining balance. One selected request lists at $0.01; two deliberate requests list at $0.02 before any applicable quota. Billing behavior for failed business responses was not tested here.
Python: preserve the layout and validate one response
Install requests with python -m pip install requests, configure the key locally and save this complete example. It uses the Model API POST route with operation parameters in the body. Catalog GET links are navigation paths, not the request method used below.
import os
import re
import json
import requests
API = "https://api.sandbase.ai/v1/api/xiaohongshu/app-v2"
def optional_json(raw):
if not isinstance(raw, str):
return None
try:
return json.loads(raw)
except (ValueError, TypeError):
return None # Keep the original field; truncated inner JSON is not a failed response.
def first_request(task, value):
if not isinstance(value, str) or not value.strip() or value != value.strip():
raise ValueError("Provide an unchanged nonblank keyword or SKU string")
if task == "search":
route = "search-products"
params = {"keyword": value, "page": 1, "search_id": "", "source": "explore_feed"}
elif task == "detail":
# Local guard for these references; the provider schema has no hex pattern.
if not re.fullmatch(r"[0-9a-fA-F]{24}", value):
raise ValueError("Choose a 24-character hexadecimal SKU string")
route = "product-detail"
params = {"sku_id": value, "source": "mall_search", "pre_page": "mall_search"}
else:
raise ValueError("Choose search or detail")
key = os.environ.get("SANDBASE_API_KEY", "").strip()
if not key:
raise ValueError("Set SANDBASE_API_KEY locally")
try:
response = requests.post(
f"{API}/{route}",
headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
json=params, timeout=(10, 90), allow_redirects=False,
)
if not 200 <= response.status_code < 300:
raise RuntimeError(f"SandBase HTTP {response.status_code}; stopped")
body = response.json()
except requests.RequestException:
raise RuntimeError("Network failure; no automatic retry") from None
except ValueError:
raise RuntimeError("Invalid response JSON") from None
if not isinstance(body, dict) or body.get("status") != "completed":
raise RuntimeError("SandBase request did not complete")
outputs = body.get("outputs")
if not isinstance(outputs, list) or not outputs or not isinstance(outputs[0], dict):
raise RuntimeError("Missing documented outputs[0]")
payload = outputs[0].get("data")
if not isinstance(payload, dict):
raise RuntimeError("Missing documented outputs[0].data object")
if type(payload.get("code")) is not int or payload["code"] != 0 or payload.get("success") is not True:
raise RuntimeError("Provider result is not integer code zero and boolean success")
data = payload.get("data")
if not isinstance(data, dict) or not isinstance(data.get("module"), dict):
raise RuntimeError("Missing layout module")
cards = data["module"].get("data")
if not isinstance(cards, list) or any(not isinstance(card, dict) for card in cards):
raise RuntimeError("Missing or malformed module data array")
if task == "search":
for card in cards:
if card.get("card_name") != "cosmos_search_goods_card":
continue
content = card.get("content")
if not isinstance(content, dict) or not isinstance(content.get("id"), str) or not content["id"]:
raise RuntimeError("Goods card has no content ID; wrapper ID is not a SKU")
else:
node = data
for field in ["biz_info", "common", "common"]:
node = node.get(field) if isinstance(node, dict) else None
if isinstance(node, dict) and "sku_id" in node and node["sku_id"] != value:
raise RuntimeError("Present echoed SKU differs from the selected SKU")
return payload
if __name__ == "__main__":
result = first_request("search", "OpenAI")
print("Returned layout cards:", len(result["data"]["module"]["data"]))For detail, replace the call inside main with result = first_request("detail", "YOUR_SELECTED_SKU"), using the actual selected hexadecimal SKU. Keep the following layout-card count line: it works for both returned shapes. Do not append detail as a second call after search. The count is layout cards, not necessarily products or variants.
The helper returns the original provider object. Unknown non-goods search cards remain present; only identified goods cards are checked for content IDs. Detail does not require direct content on every card. A present echoed SKU is compared with the selected string, while a trimmed reference with no echo is not filled with an invented value or described as independently identity-verified.
optional_json is available for a known JSON-encoded string field, but it is not applied recursively to the response. It returns None on a truncated value while leaving the raw input untouched. No eval, remote reference resolution, app navigation or media download occurs. These local checks support the observed layouts, not a guarantee that every future business schema is identical.
The search sample: six cards and one session
Saved example c2fb3714-b06c-498b-bd41-b14ec63cdeb1 was captured August 20 at 09:43:16.144 UTC. Its input was keyword OpenAI, page 1, empty search_id and source explore_feed. The complete business payload has integer code 0, boolean success true and six cosmos_search_goods_card records under data.module.data. The selected projection below retains the root pagination values and first card identity:
{
"page": 1,
"next_page": 2,
"search_id": "4e54af57e5a846c2",
"first_card": {
"card_name": "cosmos_search_goods_card",
"id": "cosmos_search_goods_card_1",
"content_id": "68922dd24daa7100015f016f"
}
}The wrapper id names a layout position; content.id is the goods identifier. The root search_id is a search session, not a SKU or credential. For a separately implemented continuation, carry that session with the returned next_page under the same query/context. The older article’s claim that pagination does not echo returned values was incorrect. This revision does not execute page 2 or claim complete keyword coverage.
The first full card has price 35.7, origin_price 42 and foreign_price text approximately £3.94. Keep these values separate. No independently verified currency/unit contract establishes a precise conversion for the raw numeric fields. stock_status 1 is a flag, not available quantity. A field named vendor_id in this capture contains an avatar URL, illustrating why a label alone cannot establish join-key semantics. The helper does not open it.
A different undated README keeps one card, a different content ID and another search session, and omits some title/price fields. One displayed reference card versus six saved cards is not a decline, a pagination result or evidence that optional fields disappeared. Keep the README’s date unknown and do not copy the August timestamp onto it.
Detail is a nested layout with separate SKU variants
Saved detail cd24f485-540f-4a68-867e-e68e400969a2 was captured August 20 at 09:40:42.848 UTC for SKU 669ddd44e05f3700011067ed, source/pre_page mall_search. It predates the search example and selects another item. Its module has header_carousel, primary, gd_comments, gd_multi_notes_card, gd_shop and gd_info_card.
The following projection records card names and whether the content key is present; it does not replace absent content with an empty object:
[
{
"card_name": "header_carousel",
"has_direct_content": true,
"nested_card_count": 0
},
{
"card_name": "primary",
"has_direct_content": false,
"nested_card_count": 2
},
{
"card_name": "gd_comments",
"has_direct_content": true,
"nested_card_count": 1
},
{
"card_name": "gd_multi_notes_card",
"has_direct_content": true,
"nested_card_count": 0
},
{
"card_name": "gd_shop",
"has_direct_content": false,
"nested_card_count": 2
},
{
"card_name": "gd_info_card",
"has_direct_content": false,
"nested_card_count": 6
}
]primary, gd_shop and gd_info_card contain nested cards. Absence of direct content therefore does not prove that a product, shop or description is missing. The carousel’s content.style.sku_list has three variants with distinct IDs; the README retains only the first. A separate new_item_id/SPU-like value must not silently replace the requested SKU. A response can contain related variants without changing which SKU the caller selected.
Historical product-detail parameter reference with required sku_id and optional source/pre_page context strings. The generated response data is empty; this is not a screenshot of the captured nested layout or proof of current stock.
The full detail includes deal_price 599 and origin_price 599. Its JSON-encoded extra_info says price_currency_origin USD, while the README prose says GBP and its shortened inner JSON is invalid after truncation. Preserve both sources and the original string. Do not reinterpret 599 as 599 dollars or 5.99 dollars, and do not crash a valid outer response merely because optional inner text cannot be decoded.
Returned delivery flags are historical context, not shipping promises. addCart buttons, shop/service links and app deeplinks are data, not actions this tutorial performs. Embedded notes and comment cards are also not proof of a complete review collection. Unresolved dollar-prefixed capture references remain unresolved rather than becoming invented lists or fetched media.
What the error tests prove
There is no complete saved negative example for either selected endpoint. The new error cases are offline mocks: malformed envelopes, booleans masquerading as integer zero, false/missing success, invalid module arrays and mismatched present SKU echoes. They show how this client stops, not what every upstream error means. A nonzero code alone does not prove deletion, unknown SKU or an authentication cause.
An explicit empty module array with valid business status remains an empty observed layout. Missing price, seller, currency or stock is unknown. No fallback converts a missing business object into success, and no retry or downstream request is hidden in parsing. Before broadening the workflow, decide how to store schema changes and which missing fields your own task actually requires.
Original design retained as history
The complete original English article and code preserve four Python blocks and the illustrative JSON below. The old extract_sku_ids function and selected sku_id were placeholders, not a runnable end-to-end onboarding example. Its shared envelope did not establish that search, detail, reviews and recommendations shared a business schema.
{
"id": "…",
"status": "completed",
"model": "xiaohongshu/app-v2/product-reviews",
"outputs": [
{
"data": {
"code": 0,
"success": true,
"data": { "…": "…" }
}
}
]
}The ellipsis ID is illustrative, not a run receipt. The original page contains no textual run UUID or dated full execution proof for the three-step chain. Review overviews, sentiment ranking, multi-keyword fan-out, recommendation cursors and scheduled monitoring remain historical design extensions. None was reinspected or called in this repair. Restoring them requires endpoint-specific evidence rather than reusing a generic code-zero check.
Historical product-reviews reference with sku_id and its own paging/filter fields, plus empty generated data. This separate endpoint is retained for context, not treated as a tested stage of the current search/detail example.
FAQ
Which ID should an agent keep from search? The content.id of an identified goods card, alongside its original card and session context. The wrapper id is not a SKU. A later detail lookup still requires an explicit choice.
Does pre_page mean the previous page number? No. For detail it is a string context field with mall_search as the documented default; it is separate from search’s integer page.
Can the returned prices be compared directly? Only after compatible currency, units and observation context are established. Raw 599, USD in one saved inner string and GBP in README prose do not establish that conversion.
Does missing direct content mean no product data? Not in these saved containers: they have nested cards. Preserve the structure before deciding which fields the application needs.
The Xiaohongshu API hub and note research guide cover neighboring tasks. Keep this integration to the chosen keyword or SKU until its actual response has been understood.
Found this useful? Share it