# Xiaohongshu KOL Analytics — Pugongying Creator API (`sian.agency/xiaohongshu-kol-analytics`) Actor Brand-side KOL intelligence for Xiaohongshu (RedNote). Search Pugongying creators with B2B filters, pull fans demographics, ROI metrics, content tags, growth history, similar-KOL discovery — the data XHS uses to match brands with creators. By SIÁN Agency. - **URL**: https://apify.com/sian.agency/xiaohongshu-kol-analytics.md - **Developed by:** [SIÁN OÜ](https://apify.com/sian.agency) (community) - **Categories:** Marketing, Business, Social media - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks - **User rating**: No ratings yet ## Pricing from $2.50 / 1,000 kol note lists This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Xiaohongshu KOL Analytics — Pugongying Creator Marketplace API 📊 [![SIÁN Agency Store](https://img.shields.io/badge/Store-SI%C3%81N%20Agency-1AE392)](https://apify.com/sian.agency?fpr=sian) [![Xiaohongshu RedNote Scraper](https://img.shields.io/badge/SI%C3%81N-Xiaohongshu%20RedNote%20Scraper-FF2741)](https://apify.com/sian.agency/xiaohongshu-rednote-scraper?fpr=sian) [![Kwai & Kuaishou Scraper](https://img.shields.io/badge/SI%C3%81N-Kwai%20%26%20Kuaishou%20Scraper-FF6E10)](https://apify.com/sian.agency/kwai-kuaishou-scraper?fpr=sian) [![Taobao & Tmall](https://img.shields.io/badge/SI%C3%81N-Taobao%20%26%20Tmall-FF4906)](https://apify.com/sian.agency/taobao-tmall-product-scraper?fpr=sian) #### 🎯 Brand-side KOL intelligence on Xiaohongshu / RedNote — the same Pugongying data XHS uses to match brands with creators ##### Built for influencer agencies, brand teams, and KOL-matching SaaS that need clean, structured creator-marketplace data — fans demographics, ROI scores, growth history, similar-creator clustering, brand-filtered B2B discovery --- ### 📋 Overview **Most Xiaohongshu scrapers stop at the consumer surface — public notes, follower counts, search results.** This actor goes deeper: it pulls the **Pugongying (蒲公英) creator-marketplace** data XHS uses internally to match brands with creators — pricing, audience demographics, ROI benchmarks, content-tag classifications, lookalike creator clustering. **Why teams choose this actor:** - ✅ **14 marketplace operations** — KOL profile · core data · ROI scores · fans demographics · growth history · note rates · content tags · similar creators · brand-filtered B2B search · note-level performance · marketplace note detail - 🎯 **Zero overlap with our [consumer-side Xiaohongshu RedNote Scraper](https://apify.com/sian.agency/xiaohongshu-rednote-scraper?fpr=sian)** — different fields, different audience, different price points. Pair them for full XHS coverage. - 🔍 **9-filter B2B Blogger Search** — keyword, fans count range, fans age band, fans gender, creator gender, content category. Build qualified shortlists in minutes. - 💰 **ROI / cost-effectiveness scoring** — Pugongying's own CPM / surpass-rate benchmarks per creator. Identify under-priced rising stars and over-priced veterans. - 📊 **Production-ready data shape** — curated camelCase aliases (userId, nickname, redId, fansCount, picturePrice, videoPrice…) plus the raw upstream fields for power users - 💵 **Pay-per-result pricing** — only charged for successful extractions, never for empty pages or errors - 🚀 **No API key, no setup, no proxies** — paste a creator ID or keyword and run --- ### ✨ Features #### Creator profile & marketplace metrics - 👤 **KOL Info** — full Pugongying profile (handle, fans count, location, personal tags, prices for picture / video notes, cooperation state) - 📊 **KOL Core Data** — core marketplace metrics + 15-day daily-data array (CPM, CPV, engagement rate) - 📈 **KOL Data Summary** — aggregate summary by `DAILY_NOTE` or `COOPERATE_NOTE` business type - 💰 **KOL Cost-Effectiveness** — picture & video read-cost, surpass-rate, CPM estimates (the highest-value B2B field) - 📋 **KOL Note Rate** — note-performance rates segmented by content tag #### Audience intelligence - 📊 **KOL Fans Trend** — 30 or 90-day time-series of total fans OR fan-increase deltas - 👥 **KOL Fans Portrait** — ages distribution, gender split, geo (provinces + cities), interests, devices - 📊 **KOL Fans Summary** — fan-base headline: active rate, engagement rate, growth-rate beyond percentile #### Content classification - 🏷️ **KOL Content Tags** — Pugongying's content-category tag set for the creator - 🏷️ **KOL Feature Tags** — audience-feature tag set #### Discovery - 🔁 **Similar KOLs** — XHS's own clustering output (~20 audience-overlapping creators per query) - 🔍 **Blogger Search** — paginated B2B creator discovery with 9 filters (the headline use case) #### Note-level data - 📝 **KOL Note List** — paginated history of a creator's published notes with read / like / save / comment metrics, sponsored / video flags - 📕 **PGY Note Detail** — marketplace-side detail view of a single note (richer than the public note view) --- ### 💡 Use cases 1. **Influencer Agency Creator Vetting** — pull full marketplace profiles before pitching XHS creators to brand clients. Fans demographics, ROI score, content tags, growth history — the same intel XHS uses to qualify them. 2. **B2B Creator Discovery with Filters** — search XHS creators with 9 brand-side filters: keyword, fans count range, fans age band, fans gender, creator gender, content category. Build qualified shortlists in minutes — not weeks of manual triage. 3. **Audience Demographics for Campaign Fit** — exact age + gender + geo distribution of any KOL's fans before paying for sponsored content. Critical for CPG, beauty, and fashion brands on RedNote. 4. **Cost-Effectiveness & ROI Benchmarking** — Pugongying's own cost-effectiveness scores and note-performance rates to benchmark creator pricing against historical performance. 5. **Lookalike-Creator Expansion** — feed one proven KOL into the similar-creator endpoint and get XHS's own clustering output. Scale successful campaigns to new but compatible creators. 6. **China Market Entry & KOL Database Building** — build proprietary KOL databases for matching SaaS, market research firms, or in-house brand teams entering the Chinese market. --- ### 🚀 How to use 1. **Pick an operation** from the dropdown — start with `🔍 Blogger Search` to find creator IDs in your target niche. 2. **Fill in the relevant input** — usually a creator userId (24-char hex) or a search keyword. 3. **For paginated operations** (Blogger Search, KOL Note List), set max pages (default 3). 4. **Run** — clean, flat dataset out. #### Example: Find beauty creators with majority female fans aged 25–34 ```json { "operation": "bloggerSearch", "keyword": "美妆", "fansAge": "AGE_25_34", "fansGender": "FE_MALE_HIGH", "fansNumberLower": 10000, "fansNumberUpper": 500000, "maxPages": 3 } ```` #### Example: Pull full ROI intel on a single creator ```json { "operation": "kolCostEffective", "userId": "636a59a2000000002302963a" } ``` #### Example: 30-day fans growth time-series ```json { "operation": "kolFansTrend", "userId": "636a59a2000000002302963a", "dateType": "DAY_30", "increaseType": "FANS_INCREASE" } ``` *** ### 💰 Pricing Pay-per-result pricing. You only pay for successful extractions — never for failed pages, empty results, or invalid IDs. | Event | Price (Bronze tier) | |---|---| | Actor start | $0.020 | | KOL Info / Core Data / Data Summary / Fans Portrait / Fans Summary / PGY Note Detail | $0.060 / row | | KOL Cost-Effectiveness / Note Rate | $0.080 / row (premium B2B fields) | | Content Tags / Feature Tags | $0.040 / row | | Blogger Search | $0.012 / row | | Similar KOLs | $0.008 / row | | Fans Trend | $0.005 / row | | KOL Note List | $0.005 / row | Free and higher-tier prices are auto-laddered by Apify based on the Bronze anchor — free-tier callers get ~3× the Bronze rate (for cost containment) and gold-tier users get tapered discounts down to flat near upstream cost. *** ### 🔗 Pair with our other Xiaohongshu actor This actor covers **brand-side** Pugongying data. For consumer-side XHS data (public notes, profiles, comments, content search), use our companion: - 📕 [Xiaohongshu RedNote Scraper](https://apify.com/sian.agency/xiaohongshu-rednote-scraper?fpr=sian) — note details, user profiles, user note catalogs, note comments, search notes, search users Zero endpoint overlap. Different fields. Different audiences. Different price points. Combine them for full XHS coverage. *** ### 🏗️ Output schema Every row carries: - `_operation` — which mode produced it (filter the dataset by this to split modes) - `_fetchedAt` — ISO-8601 UTC timestamp - `_sourceUserId` / `_sourceNoteId` / `_sourceKeyword` — source input - `_page` — page number for paginated operations - `status` — `success` | `error` - `errorMessage` — translated user-friendly error message (only on error rows) Operation-specific fields are spread alongside the curated aliases — see `dataset_schema.json` for the full field reference. *** ### 🧰 Built for production - **Retry-resilient** — automatic retry on transient HTTP 5xx and envelope code 301 ("FAILED, RETRY") with exponential backoff. - **Quota-safe failover** — silent secondary failover wired in for HTTP 402/403/408/429 quota signals. - **HTTP/2 ready** — modern axios stack, HTTPS auto-normalized on every CDN URL. - **24-char hex IDs preserved** — Xiaohongshu uses string IDs (not big-integers), so no precision-loss issues. `bigIntSafeParse` retained as a defensive guardrail for any large counters / timestamps. - **Pay-per-event** — Apify monetization wired per-operation, so you only pay for rows you actually get back. *** ### 🌐 More by SIÁN Agency - 📕 [Xiaohongshu RedNote Scraper](https://apify.com/sian.agency/xiaohongshu-rednote-scraper?fpr=sian) — consumer-side notes, profiles, comments - 🎥 [Kwai & Kuaishou Scraper](https://apify.com/sian.agency/kwai-kuaishou-scraper?fpr=sian) — short-video & creator data - 🛍️ [Taobao & Tmall Product Scraper](https://apify.com/sian.agency/taobao-tmall-product-scraper?fpr=sian) — China e-commerce - 🛒 [TikTok Shop Scraper](https://apify.com/sian.agency/tiktok-shop-scraper?fpr=sian) — TikTok Shop products & sellers - 🏠 [Zoopla Property Scraper](https://apify.com/sian.agency/zoopla-property-scraper?fpr=sian) — UK real estate listings - 🌐 [Browse all SIÁN actors →](https://apify.com/sian.agency?fpr=sian) *** ### ❓ FAQ **Do I need a Pugongying account or API key?** No. Paste a creator userId or keyword, run, get clean data out. **How do I find a creator's Pugongying userId?** Start with `🔍 Blogger Search` to discover creators in your niche — the result rows contain `userId` fields ready to feed into single-creator operations. You can also pull a userId from an XHS profile URL: `https://www.xiaohongshu.com/user/profile/{ID}`. **What's the difference vs. your other Xiaohongshu actor?** The [RedNote Scraper](https://apify.com/sian.agency/xiaohongshu-rednote-scraper?fpr=sian) returns **consumer-side** data — public notes, profiles, comments, search. This actor returns **brand-side Pugongying** data — pricing, audience demographics, ROI scores, content tags, brand-filterable creator search. Zero endpoint overlap. **Are prices in CNY or USD?** Pugongying note prices (`picturePrice`, `videoPrice`, `lowerPrice`) are in **CNY** as listed by the creator on the marketplace. The Apify actor pricing (per-result charges) is in **USD**. **What's the rate limit?** The actor handles transient HTTP 5xx and envelope code 301 with automatic retry + exponential backoff. We've measured zero rate-limit errors in normal use. **Can I get fan-growth data older than 90 days?** The Pugongying upstream caps fans-trend at `DAY_90`. For longer windows, run the trend operation periodically and concatenate the time series in your own pipeline. *** ### ⚠️ Trademark Disclaimer This is an **independent scraping tool**. It is not affiliated with, endorsed by, or sponsored by Xingyin Information Technology (Shanghai) Co., Ltd. or its Pugongying creator-marketplace platform. The Xiaohongshu®, RedNote®, 小红书®, and Pugongying®/蒲公英® names appear under nominative fair use to describe the data source. All trademarks are the property of their respective owners. *** ### 📜 Legal & ethics This actor accesses publicly available Pugongying marketplace data. Use of the data is subject to: - **Local data-protection laws** (GDPR, CCPA, China PIPL, etc.) — you are responsible for compliance in your jurisdiction. - **Xiaohongshu / Pugongying terms of service** — respect the platform's terms. - **No spam / harassment** — do not contact creators in violation of platform rules or anti-spam regulations. For Apify's broader stance on web scraping legality, see [this Apify blog post](https://blog.apify.com/is-web-scraping-legal/). *** ### 💬 Get in touch - 📩 Email: apify@sian-agency.online - 🌐 More actors: https://apify.com/sian.agency?fpr=sian - ⭐ [Leave a 5-star review](https://apify.com/sian.agency/xiaohongshu-kol-analytics/reviews) — it helps us build more features for you. # Actor input Schema ## `operation` (type: `string`): 🎯 **PICK ONE OPERATION PER RUN.** Each run produces one clean dataset matching the chosen mode. **Creator profile & marketplace metrics** - **👤 KOL Info** — full Pugongying creator profile (handle, fans, pricing, tags, location) - **📊 KOL Core Data** — core marketplace metrics + daily-data array - **📈 KOL Data Summary** — aggregate summary by content business (daily-note / cooperate-note) - **💰 KOL Cost-Effectiveness** — ROI / CPM / surpass-rate benchmarks (highest-value B2B field) - **📋 KOL Note Rate** — note-performance rates per content tag **Audience intelligence** - **📊 KOL Fans Trend** — time-series of fan count or fan-increase (DAY\_30 / DAY\_90) - **👥 KOL Fans Portrait** — demographics (age / gender / geo / interests / devices) - **📊 KOL Fans Summary** — fan-base headline summary (active rate, engagement) **Content tags** - **🏷️ KOL Content Tags** — content category tags assigned by Pugongying - **🏷️ KOL Feature Tags** — audience feature tags assigned by Pugongying **Discovery** - **🔁 Similar KOLs** — XHS's own clustering output (~20 audience-overlapping creators) - **🔍 Blogger Search** — paginated B2B creator search with 9 filters (the headline discovery op) **Note-level data** - **📝 KOL Note List** — paginated note history with performance metrics - **📕 PGY Note Detail** — marketplace-side detailed view of a single note 💡 **TIP:** Start with `Blogger Search` to find creator IDs, then drill into individual creators with `KOL Info` / `KOL Cost-Effectiveness` / `KOL Fans Portrait`. ## `userId` (type: `string`): 👤 **Required for every operation except Blogger Search.** Also required (in addition to noteId) for PGY Note Detail. The Pugongying creator userId. You can find it: - In the `userId` field of any `Blogger Search` or `Similar KOLs` result row - In a creator's Xiaohongshu profile URL: `https://www.xiaohongshu.com/user/profile/{ID}` 💡 **TIP:** Run `Blogger Search` first with a keyword + filters to surface qualified creator IDs, then drill into individual creators. ## `noteId` (type: `string`): 📕 **Required for `PGY Note Detail` only.** The marketplace note ID. Find it in `KOL Note List` result rows (`noteId` field). ⚠️ **Ignored** for all other operations. ## `keyword` (type: `string`): 🔍 **Optional for `Blogger Search`** — leave empty to browse the unfiltered top of the marketplace, or supply a keyword (Chinese or English) to filter: - `美食` (food) - `美妆` (beauty) - `母婴` (mom & baby) - `travel` 💡 **TIP:** Combine `keyword` with the filter inputs below for tightly qualified shortlists. ⚠️ **Ignored** for non-search operations. ## `searchType` (type: `string`): **Blogger Search only.** Field the keyword is matched against: - `NICKNAME` — match creator handle (default) - `NOTE` — match notes the creator has published ## `fansNumberLower` (type: `integer`): **Blogger Search filter.** Minimum fans count (inclusive). E.g. `10000` to filter out micro-influencers below 10k. ## `fansNumberUpper` (type: `integer`): **Blogger Search filter.** Maximum fans count (inclusive). E.g. `1000000` to cap at 1M and avoid mega-influencer pricing. ## `fansAge` (type: `string`): **Blogger Search filter.** Required dominant age band of the creator's fans. ## `fansGender` (type: `string`): **Blogger Search filter.** Required dominant gender skew of the creator's fans. ## `gender` (type: `string`): **Blogger Search filter.** Gender of the creator themselves. ## `contentTag` (type: `string`): **Blogger Search filter.** Pugongying content category code (e.g. `beauty`, `food`, `fashion`). Leave empty for all categories. ## `business` (type: `string`): **KOL Data Summary only.** Type of note volume to summarize. ## `dateType` (type: `string`): **KOL Fans Trend only.** Time window for the fans trend series. ## `increaseType` (type: `string`): **KOL Fans Trend only.** Which metric the time series tracks. ## `pageSize` (type: `integer`): **KOL Note List only.** Notes per page. ## `maxPages` (type: `integer`): 📄 **Applies to paginated operations** (Blogger Search, KOL Note List). Ignored for single-record operations. - **Blogger Search:** ~20 creators per page - **KOL Note List:** ~20 notes per page (configurable via Page Size) 💡 **TIP:** Start small (1–3 pages) to preview results before scaling up. ⚠️ Hard cap: 50 pages to prevent runaway runs. ## Actor input object example ```json { "operation": "bloggerSearch", "userId": "5c0fdbed00000000050043cc", "noteId": "67dee5750000000016024519", "keyword": "美妆", "searchType": "NICKNAME", "fansAge": "ALL", "fansGender": "ALL", "gender": "ALL", "business": "DAILY_NOTE", "dateType": "DAY_30", "increaseType": "FANS_TOTAL", "pageSize": 20, "maxPages": 3 } ``` # Actor output Schema ## `output` (type: `string`): Pugongying creator-marketplace rows — one flat row per KOL, time-series point, tag, or note — depending on the chosen operation. Curated camelCase aliases (userId, nickname, redId, fansCount, picturePrice, videoPrice, …) plus the raw upstream fields spread alongside. ## `report` (type: `string`): HTML report with run status, success/error row counts, success rate, pages fetched, duration, and the inputs used — written even on fatal crash. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "userId": "5c0fdbed00000000050043cc" }; // Run the Actor and wait for it to finish const run = await client.actor("sian.agency/xiaohongshu-kol-analytics").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "userId": "5c0fdbed00000000050043cc" } # Run the Actor and wait for it to finish run = client.actor("sian.agency/xiaohongshu-kol-analytics").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "userId": "5c0fdbed00000000050043cc" }' | apify call sian.agency/xiaohongshu-kol-analytics --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=sian.agency/xiaohongshu-kol-analytics", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Xiaohongshu KOL Analytics — Pugongying Creator API", "description": "Brand-side KOL intelligence for Xiaohongshu (RedNote). Search Pugongying creators with B2B filters, pull fans demographics, ROI metrics, content tags, growth history, similar-KOL discovery — the data XHS uses to match brands with creators. By SIÁN Agency.", "version": "1.1", "x-build-id": "u9x2zHpgriyxuHAh7" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/sian.agency~xiaohongshu-kol-analytics/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-sian.agency-xiaohongshu-kol-analytics", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/sian.agency~xiaohongshu-kol-analytics/runs": { "post": { "operationId": "runs-sync-sian.agency-xiaohongshu-kol-analytics", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/sian.agency~xiaohongshu-kol-analytics/run-sync": { "post": { "operationId": "run-sync-sian.agency-xiaohongshu-kol-analytics", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "operation" ], "properties": { "operation": { "title": "🎯 Operation — what do you want to extract?", "enum": [ "kolInfo", "kolCoreData", "kolDataSummary", "kolCostEffective", "kolNoteRate", "kolFansTrend", "kolFansPortrait", "kolFansSummary", "kolContentTags", "kolFeatureTags", "similarKol", "bloggerSearch", "kolNoteList", "pgyNoteDetail" ], "type": "string", "description": "🎯 **PICK ONE OPERATION PER RUN.** Each run produces one clean dataset matching the chosen mode.\n\n**Creator profile & marketplace metrics**\n- **👤 KOL Info** — full Pugongying creator profile (handle, fans, pricing, tags, location)\n- **📊 KOL Core Data** — core marketplace metrics + daily-data array\n- **📈 KOL Data Summary** — aggregate summary by content business (daily-note / cooperate-note)\n- **💰 KOL Cost-Effectiveness** — ROI / CPM / surpass-rate benchmarks (highest-value B2B field)\n- **📋 KOL Note Rate** — note-performance rates per content tag\n\n**Audience intelligence**\n- **📊 KOL Fans Trend** — time-series of fan count or fan-increase (DAY_30 / DAY_90)\n- **👥 KOL Fans Portrait** — demographics (age / gender / geo / interests / devices)\n- **📊 KOL Fans Summary** — fan-base headline summary (active rate, engagement)\n\n**Content tags**\n- **🏷️ KOL Content Tags** — content category tags assigned by Pugongying\n- **🏷️ KOL Feature Tags** — audience feature tags assigned by Pugongying\n\n**Discovery**\n- **🔁 Similar KOLs** — XHS's own clustering output (~20 audience-overlapping creators)\n- **🔍 Blogger Search** — paginated B2B creator search with 9 filters (the headline discovery op)\n\n**Note-level data**\n- **📝 KOL Note List** — paginated note history with performance metrics\n- **📕 PGY Note Detail** — marketplace-side detailed view of a single note\n\n💡 **TIP:** Start with `Blogger Search` to find creator IDs, then drill into individual creators with `KOL Info` / `KOL Cost-Effectiveness` / `KOL Fans Portrait`.", "default": "bloggerSearch" }, "userId": { "title": "👤 Creator ID (Pugongying KOL userId)", "type": "string", "description": "👤 **Required for every operation except Blogger Search.** Also required (in addition to noteId) for PGY Note Detail.\n\nThe Pugongying creator userId. You can find it:\n- In the `userId` field of any `Blogger Search` or `Similar KOLs` result row\n- In a creator's Xiaohongshu profile URL: `https://www.xiaohongshu.com/user/profile/{ID}`\n\n💡 **TIP:** Run `Blogger Search` first with a keyword + filters to surface qualified creator IDs, then drill into individual creators." }, "noteId": { "title": "📕 Note ID (for PGY Note Detail)", "type": "string", "description": "📕 **Required for `PGY Note Detail` only.** The marketplace note ID. Find it in `KOL Note List` result rows (`noteId` field).\n\n⚠️ **Ignored** for all other operations." }, "keyword": { "title": "🔍 Search Keyword (for Blogger Search)", "type": "string", "description": "🔍 **Optional for `Blogger Search`** — leave empty to browse the unfiltered top of the marketplace, or supply a keyword (Chinese or English) to filter:\n- `美食` (food)\n- `美妆` (beauty)\n- `母婴` (mom & baby)\n- `travel`\n\n💡 **TIP:** Combine `keyword` with the filter inputs below for tightly qualified shortlists.\n\n⚠️ **Ignored** for non-search operations." }, "searchType": { "title": "🔍 Search Type", "enum": [ "NICKNAME", "NOTE" ], "type": "string", "description": "**Blogger Search only.** Field the keyword is matched against:\n- `NICKNAME` — match creator handle (default)\n- `NOTE` — match notes the creator has published", "default": "NICKNAME" }, "fansNumberLower": { "title": "👥 Min fans count", "minimum": 0, "type": "integer", "description": "**Blogger Search filter.** Minimum fans count (inclusive). E.g. `10000` to filter out micro-influencers below 10k." }, "fansNumberUpper": { "title": "👥 Max fans count", "minimum": 0, "type": "integer", "description": "**Blogger Search filter.** Maximum fans count (inclusive). E.g. `1000000` to cap at 1M and avoid mega-influencer pricing." }, "fansAge": { "title": "🎂 Fans age band", "enum": [ "ALL", "LT_18", "AGE_18_24", "AGE_25_34", "AGE_35_44", "GT_44" ], "type": "string", "description": "**Blogger Search filter.** Required dominant age band of the creator's fans.", "default": "ALL" }, "fansGender": { "title": "⚧ Fans gender skew", "enum": [ "ALL", "MALE_HIGH", "FE_MALE_HIGH" ], "type": "string", "description": "**Blogger Search filter.** Required dominant gender skew of the creator's fans.", "default": "ALL" }, "gender": { "title": "⚧ Creator gender", "enum": [ "ALL", "MALE", "FEMALE" ], "type": "string", "description": "**Blogger Search filter.** Gender of the creator themselves.", "default": "ALL" }, "contentTag": { "title": "🏷️ Content category tag", "type": "string", "description": "**Blogger Search filter.** Pugongying content category code (e.g. `beauty`, `food`, `fashion`). Leave empty for all categories." }, "business": { "title": "📈 Business type (KOL Data Summary)", "enum": [ "DAILY_NOTE", "COOPERATE_NOTE" ], "type": "string", "description": "**KOL Data Summary only.** Type of note volume to summarize.", "default": "DAILY_NOTE" }, "dateType": { "title": "📅 Date range (KOL Fans Trend)", "enum": [ "DAY_30", "DAY_90" ], "type": "string", "description": "**KOL Fans Trend only.** Time window for the fans trend series.", "default": "DAY_30" }, "increaseType": { "title": "📊 Trend metric (KOL Fans Trend)", "enum": [ "FANS_TOTAL", "FANS_INCREASE" ], "type": "string", "description": "**KOL Fans Trend only.** Which metric the time series tracks.", "default": "FANS_TOTAL" }, "pageSize": { "title": "📄 Page size (KOL Note List)", "minimum": 1, "maximum": 50, "type": "integer", "description": "**KOL Note List only.** Notes per page.", "default": 20 }, "maxPages": { "title": "📄 Max pages to fetch", "minimum": 1, "maximum": 50, "type": "integer", "description": "📄 **Applies to paginated operations** (Blogger Search, KOL Note List). Ignored for single-record operations.\n\n- **Blogger Search:** ~20 creators per page\n- **KOL Note List:** ~20 notes per page (configurable via Page Size)\n\n💡 **TIP:** Start small (1–3 pages) to preview results before scaling up.\n\n⚠️ Hard cap: 50 pages to prevent runaway runs.", "default": 3 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```