샤오홍슈 search_posts API
REST 호출 한 번으로 샤오홍슈 search_posts 데이터를 조회 — 모든 플랫폼이 공유하는 안정적인 JSON 스키마로 정규화됩니다.
- 게시된 엔드포인트 1개
- GET /v1/xhs/search/posts
계약 요약(영어): Search Xiaohongshu posts (capability xhs.search_posts)
- 정규화된 응답 엔터티
- xiaohongshu/search_posts
- capability
- xhs.search_posts
모든 응답에는 신선도(cache / default / live)와 과금 메타데이터도 포함됩니다.
활용 사례
- 키워드로 {{platform}} 콘텐츠와 계정을 검색, 점수화에 바로 쓸 수 있는 정규화 결과를 반환합니다.
- 인기 주제와 핫 리스트를 추적해 떠오르는 대화를 조기에 포착.
- 검색·트렌드 쿼리에 알림을 설정해 변화를 실시간으로 인지.
응답 필드
Xiaohongshu note search response (normalized envelope)
Response envelope for GET /v1/xhs/search/posts (capability xhs.search_posts). Same normalized note entities as user_posts (search cards ship without the author block); echoes the effective query. Pages by an upstream page number behind the opaque platform cursor; the vendor search_id needed for deep pages is a pending calibration item.
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| query | string | 선택 | Echo of the effective search query. |
| data | post[] | 필수 | — |
| next_cursor | string | null | 필수 | Opaque pagination cursor; null when results are exhausted. Cursor validity is tied to the provider that produced the page. |
| meta.request_id | string | 필수 | — |
| meta.freshness.mode | cache | default | live | 필수 | — |
| meta.freshness.age_seconds | integer | null | 선택 | — |
| meta.freshness.source_layer | cache | db | upstream | 필수 | — |
| meta.freshness.stale | boolean | 선택 | — |
| meta.billing.cache_hit | boolean | 필수 | — |
| meta.billing.amount_credits | integer | 필수 | Credits actually charged for this request (the settlement unit; 1 credit = $0.0001, permanent). |
필드 비고는 계약 영문 원문으로 표시됩니다.
응답 메타데이터
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| mode | cache | default | live | 필수 | Effective mode after merging param > max_age > source policy (D-004). |
| age_seconds | integer | null | 선택 | Age of served data; null when unknown. |
| source_layer | cache | db | upstream | 필수 | Which layer served the response (PRD §10). |
| stale | boolean | 선택 | True when stale data was served under stale_if_error / SWR (D-004). |
| billing.amount_credits | integer | 필수 | Micro-USD (1e-6 USD) actually charged for this request. |
| billing.cache_hit | boolean | 필수 | — |
필드 비고는 계약 영문 원문으로 표시됩니다.
요청·응답 예시
/v1/xhs/search/postscurl -H "Authorization: Bearer $MESHDATA_API_KEY" \
"https://api.fetchpi.com/v1/xhs/search/posts?q=meshdata"{
"data": [
{
"id": "66f2c1de000000001f0167b1",
"platform": "xiaohongshu",
"type": "post",
"author": null,
"title": "search hit one",
"text": null,
"created_at": null,
"metrics": {
"likes": 512,
"collects": 0,
"comments": 0,
"shares": 0
},
"attachments": [
{
"type": "photo",
"url": "https://cdn.example.com/s1-cover.jpg"
}
],
"fetched_at": "2026-09-18T09:05:00Z"
}
],
"next_cursor": null,
"meta": {
"request_id": "req_01HTXQ8Z9HTQ",
"freshness": {
"mode": "live",
"age_seconds": 0,
"source_layer": "upstream",
"stale": false
},
"billing": {
"amount_credits": 300,
"cache_hit": false
}
}
}무료 데모
무료 계정을 만들고 API 키를 발급받으면 브라우저 Playground에서 바로 호출할 수 있습니다.
Playground에서 사용해 보기이 엔드포인트의 파라미터 표, 오류 코드, 응답 의미는 API 문서에 있습니다.
엔드포인트 레퍼런스 열기자주 묻는 질문
cache와 live 신선도의 차이는 무엇인가요?
cache는 저장된 스냅샷으로 응답하며 업스트림에 접근하지 않고, live는 더 신선한 데이터를 조회하며 추가 크레딧이 발생할 수 있습니다 — 자세한 내용은 문서의 신선도 섹션을 참조하세요.
이 엔드포인트를 무료로 써볼 수 있나요?
네 — 계정을 등록하고 API 키를 발급받으면 콘솔의 Playground에서 호출할 수 있습니다.
search_posts 능력은 어떻게 과금되나요?
Data API는 요청 단위 크레딧 과금이며 cache/live 신선도에 따라 배율이 다릅니다. 현재 능력별 가격은 가격 페이지를 기준으로 합니다.
가격
요청 단위 크레딧 과금, cache/live 신선도 옵션 — 최신 가격은 가격 페이지 기준입니다.