# Douyin Influencer Marketing Analytics — Xingtu KOL Data (`sian.agency/douyin-xingtu-kol-analytics`) Actor Brand-side Douyin influencer intelligence from the Xingtu (星图) creator marketplace. Search creators with B2B filters; pull CPM/CPE price tiers, audience & follower distribution, cost-performance and conversion ROI, growth trends, and content/comment keyword analysis. By SIÁN Agency. - **URL**: https://apify.com/sian.agency/douyin-xingtu-kol-analytics.md - **Developed by:** [SIÁN OÜ](https://apify.com/sian.agency) (community) - **Categories:** Marketing, Business, Social media - **Stats:** 3 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $6.00 / 1,000 creator searches 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 ## Douyin Influencer Marketing Analytics — Xingtu KOL Data 🚀 [![SIÁN Agency Store](https://img.shields.io/badge/Store-SI%C3%81N%20Agency-1AE392)](https://apify.com/sian.agency?fpr=sian) [![Xiaohongshu KOL Analytics](https://img.shields.io/badge/Store-Xiaohongshu%20KOL%20Analytics-FF2442)](https://apify.com/sian.agency/xiaohongshu-kol-analytics?fpr=sian) [![Douyin Shop Scraper](https://img.shields.io/badge/Store-Douyin%20Shop%20Scraper-161823)](https://apify.com/sian.agency/douyin-shop-scraper?fpr=sian) [![Kwai & Kuaishou Scraper](https://img.shields.io/badge/Store-Kwai%20%26%20Kuaishou-FF4906)](https://apify.com/sian.agency/kwai-kuaishou-scraper?fpr=sian) #### 🎉 The only Apify actor that reads Douyin's **Xingtu (星图)** creator marketplace the way ByteDance shows it to brands — CPM/CPE pricing, audience demographics, and conversion ROI ##### Built for influencer agencies, brand marketers, and China market-entry teams who vet and price Douyin KOL deals --- ### 📋 Overview **Stop guessing what a Douyin creator is worth.** This actor pulls the brand-side data straight from the Xingtu (星图) creator marketplace — the same numbers ByteDance shows advertisers when they match brands with creators. Every other "Douyin influencer" tool scrapes public video data; this one returns the marketplace economics agencies actually negotiate on. **Why influencer teams choose us:** - ✅ **Brand-side marketplace data nobody else has**: CPM/CPE suggested price tiers, e-commerce GMV ranges, cost-performance and conversion ROI — pulled from Xingtu, not reconstructed from public posts. - ⚡ **Filterable B2B creator discovery**: search the Douyin creator square by follower range, price tier, and content category. Build qualified shortlists in minutes, not weeks. - 🎯 **Exact audience demographics**: age, gender, geo, and device distribution of any creator's followers — critical for campaign-fit decisions before you spend. - 💰 **Xingtu's own ROI ranges**: expected CPM, CPE, GPM, CPC, and conversion-ability scores to benchmark pricing against real performance. - 💎 **14 operations, one clean dataset out**: pick one mode per run; no Douyin account, no login, no manual triage. --- ### ✨ Features - 👤 **Creator Profile**: full Xingtu profile — handle, followers, MCN, lowest price, tags, location, verified Douyin profile link. - 📊 **Creator Core Metrics**: marketing metrics, per-format price tiers, and industry tags. - 📺 **Creator Channel Metrics**: per-channel intro and channel-level info. - 👥 **Audience Distribution**: device / consumption / interest distribution dimensions. - 🌍 **Follower Distribution**: fan geo, age, gender, and device breakdowns. - 📈 **Follower Growth Trend**: daily follower count and deltas over any date range. - 💰 **Cost-Performance Analysis**: expected CPM / CPE / VV — the core pricing-vetting field. - 🔁 **Conversion Analysis**: GPM / CPC / sales ranges and recommended product counts. - 🔍 **Creator Search**: paginated creator-square discovery with follower / price / content-tag filters. - 🔎 **KOL Keyword Search**: simpler keyword search across Douyin, Toutiao, and Xigua. - 🎬 **Item Report Trends**: time-series performance of a single video/item. - 💬 **Comment Keyword Analysis**: hot comment tokens that reveal audience language. - 🏷️ **Content Keyword Analysis**: the creator's content hot-keyword map. - 🛍️ **Showcase Items**: the creator's latest and top-performing videos/items. --- ### 🎬 Quick Start Pick one operation, supply the matching input, run. Results land in a clean Apify dataset you can export to JSON, CSV, or Excel. ```bash curl -X POST "https://api.apify.com/v2/acts/sian.agency~douyin-xingtu-kol-analytics/runs?token=YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"operation": "creatorSearch", "keyword": "美妆", "maxPages": 2}' ```` *** ### 🚀 Getting Started (3 Simple Steps) #### Step 1: Choose your operation Pick one of the 14 modes — e.g. `creatorSearch` to discover creators, or `creatorProfile` to drill into one. #### Step 2: Provide the input Search ops need a `keyword`; per-creator ops need an `oAuthorId` (you get these from any search result row). #### Step 3: Run and export Launch the run. In seconds you'll have a structured dataset ready to export. **That's it! In under a minute, you'll have:** - A qualified shortlist of Douyin creators with marketplace pricing - Audience demographics and ROI metrics per creator - Clean rows you can pipe into a sheet, CRM, or KOL-matching tool *** ### 📥 Input Configuration | Field | Type | Required | Description | |-------|------|----------|-------------| | operation | string | **Yes** | One of the 14 operations (see Features) | | oAuthorId | string | Per-creator ops | Xingtu creator ID — find it in any search result row | | keyword | string | Search ops | Search term (Chinese or English) | | itemId | string | Item Report Trends | Douyin video/item ID from Showcase Items | | platform | string | No | `SHORT_VIDEO` (default) / `LIVE_STREAMING` / `PICTURE_TEXT` / `SHORT_DRAMA` | | followerRange | string | No | Creator Search filter, e.g. `10-100` (10k–1M followers) | | kolPriceType / kolPriceRange | string | No | Creator Search price-tier filters | | contentTag | string | No | Creator Search content-category filter | | platformSource | string | No | KOL Keyword Search: Douyin / Toutiao / Xigua | | startDate / endDate | string | No | Follower Growth Trend date range (`yyyy-MM-dd`) | | maxPages | integer | No | Pages for paginated ops (1–50, default 3) | **Example — discover creators:** ```json { "operation": "creatorSearch", "keyword": "美妆", "followerRange": "10-100", "maxPages": 2 } ``` **Example — vet one creator's pricing:** ```json { "operation": "costPerformance", "oAuthorId": "7015873824226820127" } ``` *** ### 📤 Output Results are saved to the Apify dataset. Each operation returns a flat row shape with curated camelCase aliases plus the raw upstream fields spread alongside. Filter by `_operation` to split modes. | Field | Type | Description | |-------|------|-------------| | oAuthorId | string | Xingtu creator ID | | nickname | string | Creator handle | | uniqueId | string | Douyin @handle | | follower | number | Follower count | | lowestPrice | number | Lowest marketplace price | | assignCpmSuggestPrice | number | Suggested CPM price | | ecomScore | number | E-commerce capability score | | dimension | string | Distribution dimension (audience/follower ops) | | distributionList | array | Distribution buckets | | date / fansCount / fansDelta | mixed | Follower growth time-series | | commentToken / hotRate | mixed | Comment keyword analysis | | itemTitle / playCount / likeCount | mixed | Showcase item metrics | | userPageUrl | string | Creator profile link | | status | string | `success` or `error` | **Example — Creator Profile row:** ```json { "oAuthorId": "7015873824226820127", "nickname": "美妆神手红 大大（红哒哒）", "uniqueId": "hongbaby777", "follower": 2589759, "lowestPrice": 0, "city": "杭州", "userPageUrl": "https://www.douyin.com/user/MS4wLjABAAAA...", "_operation": "creatorProfile", "status": "success" } ``` *** ### 💼 Use Cases & Examples #### 1. Influencer Agency Creator Vetting **Agency strategists pulling marketplace profiles before pitching Douyin creators to brand clients.** **Input:** `oAuthorId` of a shortlisted creator. **Output:** CPM/CPE tiers, audience distribution, cost-performance, growth history. **Use:** Walk into a client pitch with the same numbers ByteDance uses to price the deal. #### 2. B2B Creator Discovery with Filters **Brand marketers building qualified Douyin creator shortlists.** **Input:** `creatorSearch` with keyword + follower range + content tag. **Output:** A paginated list of creators matching your brand brief. **Use:** Replace weeks of manual triage with a filtered shortlist in minutes. #### 3. Audience Demographics for Campaign Fit **CPG / beauty / fashion brands targeting specific demographic segments.** **Input:** `followerDistribution` + `audienceDistribution` for a candidate creator. **Output:** Exact age, gender, geo, and device breakdowns. **Use:** Confirm a creator's audience matches your target before you pay for content. #### 4. Cost-Performance & Conversion ROI Benchmarking **Performance marketers benchmarking creator pricing vs results.** **Input:** `costPerformance` + `conversionAnalysis` across a creator set. **Output:** CPM/CPE/GPM/CPC ranges and conversion-ability scores. **Use:** Spot under-priced rising stars and over-priced veterans. #### 5. China KOL Database Building **KOL-matching SaaS founders and market-research firms.** **Input:** Recurring `creatorSearch` runs across categories. **Output:** A proprietary, structured Douyin KOL database. **Use:** Power matching products, market reports, and in-house brand tooling. *** ### 🔗 Integration Examples #### JavaScript/Node.js ```javascript import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: 'YOUR_TOKEN' }); const run = await client.actor('sian.agency/douyin-xingtu-kol-analytics').call({ operation: 'creatorSearch', keyword: '美妆', maxPages: 2 }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(items[0]); ``` #### Python ```python from apify_client import ApifyClient client = ApifyClient('YOUR_TOKEN') run = client.actor('sian.agency/douyin-xingtu-kol-analytics').call( run_input={'operation': 'creatorProfile', 'oAuthorId': '7015873824226820127'} ) for item in client.dataset(run['defaultDatasetId']).iterate_items(): print(item) ``` #### cURL ```bash curl -X POST 'https://api.apify.com/v2/acts/sian.agency~douyin-xingtu-kol-analytics/runs?token=YOUR_TOKEN' \ -H 'Content-Type: application/json' \ -d '{"operation": "audienceDistribution", "oAuthorId": "7015873824226820127"}' ``` #### Automation Workflows (N8N / Zapier / Make) 1. **Trigger**: Schedule or webhook 2. **HTTP Request**: Call the actor API with your chosen operation 3. **Process**: Handle the JSON dataset rows 4. **Action**: Save to a sheet/CRM, score creators, or notify your team *** ### 📊 Performance & Pricing #### FREE Tier (Try It Now) - Full feature access across all 14 operations, same data quality - No credit card required - Perfect for testing and small shortlists #### PAID Tier (Production Ready) - Unlimited creators and pages per run - Pay-per-result: you're only charged for successful rows — error rows are free 💰 **Premium, transparent pricing** — the headline rate is the high-volume **Creator Search** at **$0.012/row**. Deep single-creator ROI ops (cost-performance, conversion, profile) are priced higher because the data has no substitute anywhere else on the market. 🔗 [View current pricing](https://apify.com/sian.agency/douyin-xingtu-kol-analytics?fpr=sian) *** ### ❓ Frequently Asked Questions **Q: What is Xingtu (星图)?** A: Xingtu is Douyin's official creator marketplace where brands find, vet, and pay creators. This actor surfaces that brand-side data — pricing, audience, ROI — as a structured dataset. **Q: How do I get a creator's `oAuthorId`?** A: Run `creatorSearch` or `kolKeywordSearch` first — every result row includes `oAuthorId`. Then use it in any per-creator operation. **Q: How many creators can I pull?** A: FREE tier covers testing; PAID is unlimited. Paginated search ops return ~20 creators per page, up to 50 pages. **Q: What output formats are available?** A: JSON, CSV, and Excel — export directly from the Apify dataset. **Q: Does it need a Douyin or Xingtu account?** A: No. No login, no account, no API key from your side. **Q: Why is some data thin for a given creator or item?** A: Smaller creators and low-traffic items have less marketplace data on file. The actor returns a clear status row when a particular endpoint has no data for that input. **Q: Is this legal?** A: We only extract publicly accessible marketplace data. See the legal section below. *** ### 🐛 Troubleshooting **"Missing required input" error** - Per-creator ops need `oAuthorId`; `kolKeywordSearch` needs `keyword`; `itemReportTrends` needs `itemId`. Check the operation's required field. **A creator returns "No distribution data available"** - That creator has no marketplace data on file for that dimension. Try a larger creator or a different operation. **Search returns fewer pages than `maxPages`** - The marketplace ran out of matching creators; the actor stops automatically when there are no more results. **"Data source temporarily unavailable"** - A transient upstream hiccup. The actor retries automatically; re-run if it persists. *** ### ⚠️ Trademark Disclaimer This is an **independent scraping tool**. It is not affiliated with, endorsed by, or sponsored by ByteDance Ltd., Douyin, or the Xingtu (星图) creator-marketplace platform. The Douyin®, 抖音®, and Xingtu®/星图® names appear under nominative fair use to describe the data this tool works with. *** ### ⚖️ Is it legal to scrape data? Our actors are ethical and do not extract any private user data, such as email addresses, gender, or location. They only extract what the user has chosen to share publicly. We therefore believe that our actors, when used for ethical purposes by Apify users, are safe. However, you should be aware that your results could contain personal data. Personal data is protected by the **GDPR** in the European Union and by other regulations around the world. You should not scrape personal data unless you have a legitimate reason to do so. If you're unsure whether your reason is legitimate, consult your lawyers. You can also read Apify's blog post on the [legality of web scraping](https://blog.apify.com/is-web-scraping-legal/). *** ### 🤝 Support [![Telegram Support](https://img.shields.io/badge/Telegram-Support%20Group-0088cc?logo=telegram)](https://t.me/+vyh1sRE08sAxMGRi) **Join our active support community** - For issues or questions, open an issue in the actor's Issues tab - Check the [SIÁN Agency Store](https://apify.com/sian.agency?fpr=sian) for more automation tools - 📧 *** **Built by [SIÁN Agency](https://www.sian-agency.online)** | **[More Tools](https://apify.com/sian.agency?fpr=sian)** # 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** - **👤 Creator Profile** — full Xingtu creator profile (handle, followers, MCN, pricing, tags, location) - **📊 Creator Core Metrics** — marketing metrics + price tiers + industry tags - **📺 Creator Channel Metrics** — per-channel intro & info **Audience intelligence** - **👥 Audience Distribution** — device / consumption / interest distribution dimensions - **🌍 Follower Distribution** — fan geo / age / gender / device distribution - **📈 Follower Growth Trend** — daily follower count + deltas over a date range **ROI & cost** - **💰 Cost-Performance Analysis** — expected CPM / CPE / VV (the core pricing-vetting field) - **🔁 Conversion Analysis** — GPM / CPC / sales ranges, recommended product counts **Discovery** - **🔍 Creator Search** — paginated creator-square search with follower/price/tag filters (the headline discovery op) - **🔎 KOL Keyword Search** — simpler keyword creator search across Douyin / Toutiao / Xigua **Content & item intelligence** - **🎬 Item Report Trends** — time-series performance of a single video/item - **💬 Comment Keyword Analysis** — hot comment tokens (audience language) - **🏷️ Content Keyword Analysis** — content hot-keyword map - **🛍️ Showcase Items** — the creator's latest + top-performing videos/items 💡 **TIP:** Start with `Creator Search` to find creator IDs, then drill into individual creators with `Creator Profile` / `Cost-Performance Analysis` / `Audience Distribution`. ## `oAuthorId` (type: `string`): 👤 **Required for every operation except Creator Search, KOL Keyword Search, and Item Report Trends.** The Xingtu creator (author) ID. You can find it: - In the `oAuthorId` / `starId` field of any `Creator Search` or `KOL Keyword Search` result row 💡 **TIP:** Run `Creator Search` first with a keyword + filters to surface qualified creator IDs, then drill into individual creators. ## `itemId` (type: `string`): 🎬 **Required for `Item Report Trends` only.** A Douyin video/item ID. Find it in `Showcase Items` result rows (`itemId` field). ⚠️ **Ignored** for all other operations. ## `keyword` (type: `string`): 🔍 **Required for `KOL Keyword Search`; optional for `Creator Search`** (leave empty to browse the unfiltered creator square). Chinese or English: - `美妆` (beauty) - `美食` (food) - `母婴` (mom & baby) - `travel` 💡 **TIP:** Combine `keyword` with the filter inputs below for tightly qualified shortlists. ⚠️ **Ignored** for non-search operations. ## `searchType` (type: `string`): **Creator Search only.** Field the keyword is matched against. ## `followerRange` (type: `string`): **Creator Search filter.** Follower count range in 万 (10k) units, e.g. `10-100` for 100k–1M followers. Leave empty for all sizes. ## `kolPriceType` (type: `string`): **Creator Search filter.** Pricing dimension to filter on, e.g. `视频1_20s` (1-20s video). Leave empty for all. ## `kolPriceRange` (type: `string`): **Creator Search filter.** Price range in yuan paired with the price type, e.g. `10000-50000`. Leave empty for all. ## `contentTag` (type: `string`): **Creator Search filter.** Content category tag. Leave empty for all categories. ## `platformSource` (type: `string`): **KOL Keyword Search only.** Which platform to search. ## `platform` (type: `string`): **Per-creator ops.** Which content channel the metrics describe. ## `linkType` (type: `string`): **Audience Distribution only.** Audience funnel stage. ## `authorType` (type: `string`): **Follower Distribution only.** Which fan cohort to profile. ## `range` (type: `string`): **Conversion Analysis only.** Time window for conversion metrics. ## `startDate` (type: `string`): **Follower Growth Trend only.** Start date in `yyyy-MM-dd`. Defaults to 30 days ago if empty. ## `endDate` (type: `string`): **Follower Growth Trend only.** End date in `yyyy-MM-dd`. Defaults to today if empty. ## `onlyAssign` (type: `boolean`): **Showcase Items only.** Include only assigned (sponsored) items. ## `flowType` (type: `string`): **Showcase Items only.** Whether to include or exclude paid-flow items. ## `maxPages` (type: `integer`): 📄 **Applies to paginated operations** (Creator Search, KOL Keyword Search). Ignored for single-record operations. - \~20 creators per page 💡 **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": "creatorSearch", "oAuthorId": "7015873824226820127", "itemId": "7643365207473534373", "keyword": "美妆", "searchType": "NICKNAME", "followerRange": "10-100", "platformSource": "_1", "platform": "SHORT_VIDEO", "linkType": "CONNECTED", "authorType": "FAN", "range": "DAY_30", "startDate": "2026-04-26", "endDate": "2026-05-26", "onlyAssign": false, "flowType": "EXCLUDE", "maxPages": 3 } ``` # Actor output Schema ## `results` (type: `string`): Xingtu creator-marketplace rows — one flat row per creator, distribution dimension, time-series point, keyword, or item — depending on the chosen operation. Curated camelCase aliases (oAuthorId, nickname, follower, lowestPrice, assignCpmSuggestPrice, ecomScore, …) plus the raw upstream fields spread alongside. ## `htmlReport` (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 = { "oAuthorId": "7015873824226820127" }; // Run the Actor and wait for it to finish const run = await client.actor("sian.agency/douyin-xingtu-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 = { "oAuthorId": "7015873824226820127" } # Run the Actor and wait for it to finish run = client.actor("sian.agency/douyin-xingtu-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 '{ "oAuthorId": "7015873824226820127" }' | apify call sian.agency/douyin-xingtu-kol-analytics --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=sian.agency/douyin-xingtu-kol-analytics", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Douyin Influencer Marketing Analytics — Xingtu KOL Data", "description": "Brand-side Douyin influencer intelligence from the Xingtu (星图) creator marketplace. Search creators with B2B filters; pull CPM/CPE price tiers, audience & follower distribution, cost-performance and conversion ROI, growth trends, and content/comment keyword analysis. By SIÁN Agency.", "version": "1.0", "x-build-id": "dvgftkUuYGmgDQOA9" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/sian.agency~douyin-xingtu-kol-analytics/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-sian.agency-douyin-xingtu-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~douyin-xingtu-kol-analytics/runs": { "post": { "operationId": "runs-sync-sian.agency-douyin-xingtu-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~douyin-xingtu-kol-analytics/run-sync": { "post": { "operationId": "run-sync-sian.agency-douyin-xingtu-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": [ "creatorProfile", "creatorCoreMetrics", "creatorChannelMetrics", "audienceDistribution", "followerDistribution", "followerGrowthTrend", "costPerformance", "conversionAnalysis", "creatorSearch", "kolKeywordSearch", "itemReportTrends", "kolCommentKeywords", "kolContentKeywords", "showcaseItems" ], "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- **👤 Creator Profile** — full Xingtu creator profile (handle, followers, MCN, pricing, tags, location)\n- **📊 Creator Core Metrics** — marketing metrics + price tiers + industry tags\n- **📺 Creator Channel Metrics** — per-channel intro & info\n\n**Audience intelligence**\n- **👥 Audience Distribution** — device / consumption / interest distribution dimensions\n- **🌍 Follower Distribution** — fan geo / age / gender / device distribution\n- **📈 Follower Growth Trend** — daily follower count + deltas over a date range\n\n**ROI & cost**\n- **💰 Cost-Performance Analysis** — expected CPM / CPE / VV (the core pricing-vetting field)\n- **🔁 Conversion Analysis** — GPM / CPC / sales ranges, recommended product counts\n\n**Discovery**\n- **🔍 Creator Search** — paginated creator-square search with follower/price/tag filters (the headline discovery op)\n- **🔎 KOL Keyword Search** — simpler keyword creator search across Douyin / Toutiao / Xigua\n\n**Content & item intelligence**\n- **🎬 Item Report Trends** — time-series performance of a single video/item\n- **💬 Comment Keyword Analysis** — hot comment tokens (audience language)\n- **🏷️ Content Keyword Analysis** — content hot-keyword map\n- **🛍️ Showcase Items** — the creator's latest + top-performing videos/items\n\n💡 **TIP:** Start with `Creator Search` to find creator IDs, then drill into individual creators with `Creator Profile` / `Cost-Performance Analysis` / `Audience Distribution`.", "default": "creatorSearch" }, "oAuthorId": { "title": "👤 Creator ID (oAuthorId / star_id)", "type": "string", "description": "👤 **Required for every operation except Creator Search, KOL Keyword Search, and Item Report Trends.**\n\nThe Xingtu creator (author) ID. You can find it:\n- In the `oAuthorId` / `starId` field of any `Creator Search` or `KOL Keyword Search` result row\n\n💡 **TIP:** Run `Creator Search` first with a keyword + filters to surface qualified creator IDs, then drill into individual creators." }, "itemId": { "title": "🎬 Item ID (for Item Report Trends)", "type": "string", "description": "🎬 **Required for `Item Report Trends` only.** A Douyin video/item ID. Find it in `Showcase Items` result rows (`itemId` field).\n\n⚠️ **Ignored** for all other operations." }, "keyword": { "title": "🔍 Search Keyword", "type": "string", "description": "🔍 **Required for `KOL Keyword Search`; optional for `Creator Search`** (leave empty to browse the unfiltered creator square). Chinese or English:\n- `美妆` (beauty)\n- `美食` (food)\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 (Creator Search)", "enum": [ "NICKNAME", "NOTE" ], "type": "string", "description": "**Creator Search only.** Field the keyword is matched against.", "default": "NICKNAME" }, "followerRange": { "title": "👥 Follower range (Creator Search)", "type": "string", "description": "**Creator Search filter.** Follower count range in 万 (10k) units, e.g. `10-100` for 100k–1M followers. Leave empty for all sizes." }, "kolPriceType": { "title": "💰 Price type (Creator Search)", "type": "string", "description": "**Creator Search filter.** Pricing dimension to filter on, e.g. `视频1_20s` (1-20s video). Leave empty for all." }, "kolPriceRange": { "title": "💰 Price range (Creator Search)", "type": "string", "description": "**Creator Search filter.** Price range in yuan paired with the price type, e.g. `10000-50000`. Leave empty for all." }, "contentTag": { "title": "🏷️ Content tag (Creator Search)", "type": "string", "description": "**Creator Search filter.** Content category tag. Leave empty for all categories." }, "platformSource": { "title": "🔎 Platform source (KOL Keyword Search)", "enum": [ "_1", "_2", "_3" ], "type": "string", "description": "**KOL Keyword Search only.** Which platform to search.", "default": "_1" }, "platform": { "title": "📺 Platform channel", "enum": [ "SHORT_VIDEO", "LIVE_STREAMING", "PICTURE_TEXT", "SHORT_DRAMA" ], "type": "string", "description": "**Per-creator ops.** Which content channel the metrics describe.", "default": "SHORT_VIDEO" }, "linkType": { "title": "🔗 Link type (Audience Distribution)", "enum": [ "CONNECTED", "AWARE", "INTERESTED", "LIKE", "FOLLOW" ], "type": "string", "description": "**Audience Distribution only.** Audience funnel stage.", "default": "CONNECTED" }, "authorType": { "title": "🌍 Fan type (Follower Distribution)", "enum": [ "FAN", "DIE_HARD_FAN" ], "type": "string", "description": "**Follower Distribution only.** Which fan cohort to profile.", "default": "FAN" }, "range": { "title": "📅 Range (Conversion Analysis)", "enum": [ "DAY_30", "DAY_90" ], "type": "string", "description": "**Conversion Analysis only.** Time window for conversion metrics.", "default": "DAY_30" }, "startDate": { "title": "📅 Start date (Follower Growth Trend)", "type": "string", "description": "**Follower Growth Trend only.** Start date in `yyyy-MM-dd`. Defaults to 30 days ago if empty." }, "endDate": { "title": "📅 End date (Follower Growth Trend)", "type": "string", "description": "**Follower Growth Trend only.** End date in `yyyy-MM-dd`. Defaults to today if empty." }, "onlyAssign": { "title": "🛍️ Only assigned items (Showcase Items)", "type": "boolean", "description": "**Showcase Items only.** Include only assigned (sponsored) items.", "default": false }, "flowType": { "title": "🛍️ Flow type (Showcase Items)", "enum": [ "EXCLUDE", "INCLUDE" ], "type": "string", "description": "**Showcase Items only.** Whether to include or exclude paid-flow items.", "default": "EXCLUDE" }, "maxPages": { "title": "📄 Max pages to fetch", "minimum": 1, "maximum": 50, "type": "integer", "description": "📄 **Applies to paginated operations** (Creator Search, KOL Keyword Search). Ignored for single-record operations.\n\n- ~20 creators per page\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 } } } } } } } } } } ```