Xiaohongshu profile API

Xiaohongshu profile data in one REST call — normalized to the stable JSON schema shared across every FetchPI platform.

1 documented endpoints
GET /v1/xhs/users/{username}

Contract summary (English): Get a normalized Xiaohongshu profile (capability xhs.profile)

Normalized response entity: xiaohongshu/profile
capability: xhs.profile

Every response also carries freshness (cache / default / live) and billing metadata.

Use cases

Enrich CRM and outreach tooling with up-to-date {{platform}} profile data — follower counts, verification status and bios as structured JSON.
Screen creator and partner accounts before a campaign with consistent, queryable profile metrics.
Re-query the same handle and diff the normalized fields to track profile changes over time.

Response fields

Xiaohongshu Profile (normalized)

Normalized Xiaohongshu (RED) creator profile. This is the ONLY upper-layer format; provider-private fields MUST NOT appear here — the Normalizer drops them. The capability id is xhs.profile (the /v1/xhs surface; the URL prefix xhs. maps to this xiaohongshu entity platform at entity resolution).

Field	Type	Required	Description
id	string	Required	Platform-stable user id (the numeric xiaohongshu user_id).
platform	"xiaohongshu"	Required	—
type	"profile"	Required	—
username	string	Required	The xiaohongshu red_id (public handle); the numeric user id when the surface omits red_id.
display_name	string \| null	Optional	The xiaohongshu nickname.
description	string \| null	Optional	The profile bio.
url	string \| null	Optional	—
profile_image_url	string \| null	Optional	—
verified	boolean	Required	Official account verification.
created_at	string \| null	Optional	Account creation time, UTC RFC3339; null — the platform does not expose it.
metrics.followers	integer	Required	Fans count.
metrics.following	integer	Required	—
metrics.posts	integer	Required	Note count.
metrics.likes	integer	Optional	Lifetime likes received across notes; omitted when unknown.
fetched_at	string	Required	When the platform data was actually collected (UTC RFC3339).

Field notes are shown in the contract's original English.

Response meta

Field	Type	Required	Description
mode	cache \| default \| live	Required	Effective mode after merging param > max_age > source policy (D-004).
age_seconds	integer \| null	Optional	Age of served data; null when unknown.
source_layer	cache \| db \| upstream	Required	Which layer served the response (PRD §10).
stale	boolean	Optional	True when stale data was served under stale_if_error / SWR (D-004).
billing.amount_credits	integer	Required	Micro-USD (1e-6 USD) actually charged for this request.
billing.cache_hit	boolean	Required	—

Field notes are shown in the contract's original English.

Example request & response

GET/v1/xhs/users/{username}

curl -H "Authorization: Bearer $MESHDATA_API_KEY" \
  "https://api.fetchpi.com/v1/xhs/users/newdev"

{
  "data": {
    "id": "66f2a1de000000001e0167a1",
    "platform": "xiaohongshu",
    "type": "profile",
    "username": "creatordev",
    "display_name": "Creator Dev",
    "description": "Notes about data APIs.",
    "profile_image_url": "https://cdn.example.com/avatar/creatordev.jpg",
    "verified": true,
    "created_at": null,
    "metrics": {
      "followers": 51230,
      "following": 310,
      "posts": 862,
      "likes": 2140000
    },
    "fetched_at": "2026-09-18T09:00:00Z"
  },
  "meta": {
    "request_id": "req_01HTXQ8Z9HTQ",
    "freshness": {
      "mode": "default",
      "age_seconds": 120,
      "source_layer": "db",
      "stale": false
    },
    "billing": {
      "amount_credits": 100,
      "cache_hit": false
    }
  }
}

Free demo

Create a free account, grab an API key and call this endpoint from the browser-based Playground.

Try it in the Playground

Parameter tables, error codes and response semantics for this endpoint live in the API documentation.

Open the endpoint reference

Frequently asked questions

What does the Xiaohongshu profile API return?

A normalized profile object — identity, bio and audience fields as defined in the field table below — plus freshness and billing metadata.

Can I try this endpoint for free?

Yes — register an account, grab an API key and call it from the Playground in the console.

How is the profile capability billed?

Data API calls are billed per request in credits, with different cache/live freshness multipliers. Current per-capability prices live on the pricing page.

Pricing

Per-request credit billing with cache/live freshness options — current prices live on the pricing page.

View pricing Browse all APIs