# Douyin Xingtu 巨量星图 KOL Scraper - Rates, CPM & Rankings (`clover_folktale/xingtu-scraper`) Actor

Get Douyin KOL data from Xingtu (巨量星图) for influencer marketing: search creators by keyword, category, gender and followers; pull video quotes, expected CPM/CPE, MCN and audience breakdown; read Xingtu ranking lists. No login or cookies needed. Export to JSON, CSV or Excel.

- **URL**: https://apify.com/clover_folktale/xingtu-scraper.md
- **Developed by:** [Silkline](https://apify.com/clover_folktale) (community)
- **Categories:** Social media, Lead generation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $7.50 / 1,000 creator rows

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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

Douyin Xingtu 巨量星图 KOL Scraper collects Douyin KOL and influencer data from Xingtu (巨量星图), Douyin's official creator marketplace. Find creators by keyword, category, gender and follower range, pull a creator's full profile with video quotes, expected CPM and CPE, agency (MCN) and audience breakdown, and read Xingtu's commercial rankings, all as clean, flat JSON. It is made for brands, agencies and analysts who plan influencer marketing and brand deals on Douyin. No Douyin account, API keys, proxies or cookies needed.

### What is Xingtu?

Xingtu (巨量星图, often just called 星图) is Douyin's official marketplace where brands find creators and book sponsored videos. Creators set quotes for different video lengths, and Xingtu shows performance figures, audience statistics and weekly or monthly rankings of creators by commercial results or growth. This Actor reads the data Xingtu publishes about creators; it is not affiliated with Douyin or Xingtu.

### What data can you get?

The Actor has three modes. Each record has a `type` field that tells you which kind of record it is.

| Mode | Give it | You get | Record `type` |
|---|---|---|---|
| `search` | optional keyword; optional category, gender, follower range, sort | creators with followers, quotes, expected plays, CPM/CPE, indexes and recent videos | `creator` |
| `creator` | Xingtu creator IDs or creator page links | one full profile per creator: base data, performance, expected CPM/CPE, agency and audience breakdown | `creatorDetail` |
| `ranking` | a ranking list, period and category (optional date) | the ranked creators with rank, previous rank and the list's own figures | `rankedCreator` |

#### Shared fields

| Field | What it is |
|---|---|
| `userId` | Xingtu creator ID (use it as input for mode `creator`) |
| `nickname` | Creator name |
| `followers` | Follower count |
| `categories` | Creator categories |
| `subCategories` | Creator sub-categories |
| `contentThemes` | Content themes (last 180 days in search and ranking rows) |
| `url` | Xingtu page of the creator |
| `avatar` | Avatar image link |
| `douyinUserId` | The creator's Douyin user ID |
| `gender` | `male` or `female` |
| `city`, `province` | City and province shown on the creator's profile |

#### Search results (`creator`)

| Field | What it is |
|---|---|
| `price20To60s` | Quote in CNY for a 21-60 second video |
| `price60sPlus` | Quote in CNY for a video over 60 seconds |
| `expectedPlays` | Expected plays per video |
| `expectedCpm20To60s`, `expectedCpm60sPlus` | Expected cost per thousand plays (CNY) for each video length |
| `expectedCpe20To60s`, `expectedCpe60sPlus` | Expected cost per engagement (CNY) for each video length |
| `medianPlays30d` | Median plays of the last 30 days |
| `medianInteractions30d` | Median interactions (likes, comments, shares) of the last 30 days |
| `interactionRate30d` | Interaction rate of the last 30 days, as a fraction |
| `playCompletionRate30d` | Share of plays watched to the end in the last 30 days, as a fraction |
| `followersGrowth30d` | Followers gained in the last 30 days |
| `followersGrowthRate15d` | Follower growth over the last 15 days, as a fraction (0.01 = 1%) |
| `starIndex`, `spreadIndex`, `conversionIndex`, `shoppingIndex` | Xingtu star, spread, conversion and shopping indexes |
| `ecommerceEnabled` | Whether the creator sells products |
| `ecommerceLevel` | E-commerce level, for example `L1` |
| `ecommerceGmv30dRange` | Sales range of the last 30 days, as Xingtu shows it |
| `recentVideos` | The creator's last videos with plays, likes, comments, shares and publish time |

#### Creator profiles (`creatorDetail`)

| Field | What it is |
|---|---|
| `price20To60s`, `price60sPlus` | Video quotes in CNY |
| `expectedCpm20To60s`, `expectedCpe20To60s`, `expectedCpm60sPlus`, `expectedCpe60sPlus` | Expected CPM and CPE (CNY) per video length |
| `salesExpectedCpm20To60s`, `salesExpectedCpm60sPlus` | Expected CPM (CNY) in sales campaigns per video length |
| `audience` | Audience breakdown by kind: `gender`, `age`, `province`, `city`, `cityTier`, `deviceBrand`, `interest`, `crowd`. Each is a list of `{label, count, share}` with share in percent |
| `mcnName`, `mcnId`, `mcnLogo`, `mcnIntroduction` | Agency (MCN) the creator belongs to, its ID, logo link and introduction |
| `medianPlays` | Median plays per video |
| `averageLikes`, `averageComments`, `averageShares` | Averages per video |
| `averageVideoSeconds` | Average video length in seconds |
| `interactionRate`, `playCompletionRate` | Interaction and play completion rates, as fractions |
| `ecommerceEnabled` | Whether the creator sells products |
| `selfIntroduction` | The creator's own pitch to brands |
| `creditScore` | Xingtu credit score |
| `cooperationBrands` | Brands the creator lists as past partners |
| `email`, `wechat`, `hasWechat` | Business e-mail and WeChat ID the creator published for brands, and whether a WeChat contact is on file |
| `douyinSecUid` | Douyin sec_uid, usable for Douyin profile lookups |
| `douyinShortId`, `douyinUniqueId` | Douyin short ID and Douyin ID (the public handle) |
| `joinedAt`, `updatedAt` | When the creator joined Xingtu and when the profile was last updated (ISO 8601) |

#### Ranking rows (`rankedCreator`)

| Field | What it is |
|---|---|
| `rank` | Position in the ranking |
| `previousRank` | Position in the previous edition |
| `isNew` | Whether the creator is new in this edition |
| `score` | Ranking score |
| `primaryCategory` | Main content category |
| `averagePlays` | Average plays per video |
| `cpm` | Cost per thousand plays |
| `followersGained`, `videoCount` | Followers gained and videos published in the period (rising-stars list) |
| `completedOrders` | Completed Xingtu orders as a band, for example `> 20` (brand lists) |
| `repurchaseRate` | Advertiser repurchase rate as a band, for example `> 0.75` (brand lists) |
| `orderRate` | Share of the creator's videos that are paid orders (brand lists) |

The dataset has three ready-made table views: Creators, Creator profiles and Rankings.

### How to use Douyin Xingtu KOL Scraper

1. Open the Actor in Apify Console.
2. Choose a mode: Find creators (`search`), Creator profiles (`creator`) or Ranking lists (`ranking`).
3. Fill in the inputs for that mode, for example a keyword and a follower range, a list of creator IDs, or a ranking list and category.
4. Set Max results. You are charged per item returned, never for more than this number.
5. Click Start and wait for the run to finish.
6. Open the dataset and export it as JSON, CSV or Excel, or read it through the API.

An empty input `{}` also works: it browses the top creators.

### Input

| Field | Type | Required | What it does | Default |
|---|---|---|---|---|
| `mode` | string | required | `search`, `creator` or `ranking` | `search` |
| `keyword` | string | optional | Mode search: creator nickname, or with `searchBy` = `content` a topic found in the creators' videos. Leave empty to browse with filters only | none |
| `searchBy` | string | optional | Mode search: match the keyword against `nickname` or `content` | `nickname` |
| `category` | string | optional | Mode search: only creators in this category | `any` |
| `gender` | string | optional | Mode search: `any`, `male` or `female` | `any` |
| `minFollowers` | integer | optional | Mode search: only creators with at least this many followers | none |
| `maxFollowers` | integer | optional | Mode search: only creators with at most this many followers | none |
| `sort` | string | optional | Mode search: `relevance`, `followers-desc` or `followers-asc` | `relevance` |
| `creators` | array of strings | optional | Mode creator: Xingtu creator IDs (the `userId` returned by search) or Xingtu creator page links | none |
| `rankingList` | string | optional | Mode ranking: which ranking list to read | `brand-preferred` |
| `rankingPeriod` | string | optional | Mode ranking: `weekly` or `monthly` edition | `monthly` |
| `rankingCategory` | string | optional | Mode ranking: industry or content category. Leave unset for the default of the chosen list | default of the list |
| `rankingDate` | string | optional | Mode ranking: edition to read as YYYYMMDD, the last day of the period (e.g. `20260930` for the September 2026 monthly edition). Empty reads the latest edition | none |
| `maxResults` | integer | optional | Maximum number of items in total for this run (1 to 5000) | `20` |

#### Option values

- `category` (search): `any`, `beauty`, `fashion`, `pets`, `reviews`, `games`, `anime`, `travel`, `cars`, `lifestyle`, `music`, `dance`, `food`, `parenting`, `fitness`, `tech`, `education`, `looks`, `home`, `talent`, `film-tv`, `art-culture`, `finance`, `rural`, `comedy-drama`, `relationships`, `gardening`, `real-estate`, `street-snaps`, `media`.
- `rankingList`: `brand-preferred` (brand seeding), `a3-seeding`, `search-after-view`, `ecommerce` (sales), `ad-traffic`, `high-potential`, `rising-stars` (follower growth), `top-picks` (head creators).
- `rankingCategory`, industry categories for the lists brand-preferred, a3-seeding, search-after-view, ecommerce, ad-traffic and high-potential: `electronics`, `daily-chemicals`, `apparel`, `mom-baby-pet`, `auto`, `beauty`, `food-beverage`.
- `rankingCategory`, content categories for the lists rising-stars and top-picks: `all`, `drama`, `anime`, `parenting`, `entertainment`, `sports`, `animals`, `emotion`, `photography`, `education`, `travel`, `fashion`, `games`, `home-life`, `life-records`, `movies`, `tv-series`, `tech`, `science`, `variety`, `food`, `workplace`, `dance`, `art`, `finance`, `music`, `looks`, `rural`, `cars`, `law`.

#### Example: find food creators with 100k-500k followers

```json
{
  "mode": "search",
  "keyword": "美食",
  "category": "food",
  "minFollowers": 100000,
  "maxFollowers": 500000,
  "sort": "followers-desc",
  "maxResults": 100
}
```

#### Example: find creators by what their videos are about

```json
{
  "mode": "search",
  "keyword": "露营",
  "searchBy": "content",
  "category": "travel",
  "gender": "female",
  "maxResults": 40
}
```

#### Example: full creator profiles

```json
{
  "mode": "creator",
  "creators": ["6839869628747874312"]
}
```

You can also paste a creator page link such as `https://www.xingtu.cn/ad/creator/author-homepage/douyin-video/6839869628747874312`.

#### Example: weekly rising-stars ranking for food

```json
{
  "mode": "ranking",
  "rankingList": "rising-stars",
  "rankingPeriod": "weekly",
  "rankingCategory": "food",
  "maxResults": 100
}
```

#### Example: an earlier monthly brand-preferred ranking for beauty

```json
{
  "mode": "ranking",
  "rankingList": "brand-preferred",
  "rankingPeriod": "monthly",
  "rankingCategory": "beauty",
  "rankingDate": "20260930",
  "maxResults": 100
}
```

### Output example

All values below are illustrative samples.

#### Search result (`creator`)

```json
{
  "type": "creator",
  "userId": "6800000000000000001",
  "url": "https://www.xingtu.cn/ad/creator/author-homepage/douyin-video/6800000000000000001",
  "nickname": "示例美食达人",
  "avatar": "https://p3.douyinpic.com/aweme/1080x1080/aweme-avatar/sample.jpeg",
  "douyinUserId": "10000000001",
  "gender": "male",
  "city": "杭州市",
  "province": "浙江省",
  "followers": 2150000,
  "followersGrowth30d": 18400,
  "followersGrowthRate15d": 0.0042,
  "categories": ["美食"],
  "subCategories": ["美食教程"],
  "contentThemes": ["家常菜"],
  "price20To60s": 13000,
  "price60sPlus": 15000,
  "expectedPlays": 390000,
  "medianPlays30d": 305000,
  "medianInteractions30d": 5300,
  "interactionRate30d": 0.0174,
  "playCompletionRate30d": 0.21,
  "expectedCpm20To60s": 33.33,
  "expectedCpe20To60s": 1.88,
  "expectedCpm60sPlus": 38.46,
  "expectedCpe60sPlus": 2.17,
  "starIndex": 78.5,
  "spreadIndex": 72.1,
  "conversionIndex": 65.3,
  "shoppingIndex": 60.2,
  "ecommerceEnabled": false,
  "ecommerceLevel": null,
  "ecommerceGmv30dRange": null,
  "recentVideos": [
    {"videoId": "7600000000000000001", "title": "...", "plays": 335000, "likes": 4900, "comments": 116, "shares": 1230, "publishedAt": "2026-10-01T09:30:00Z"}
  ]
}
```

#### Creator profile (`creatorDetail`)

```json
{
  "type": "creatorDetail",
  "userId": "6800000000000000001",
  "nickname": "示例美食达人",
  "followers": 2150000,
  "douyinSecUid": "MS4wLjABAAAAsample",
  "douyinShortId": "100000001",
  "douyinUniqueId": "sample_food",
  "mcnName": "示例MCN机构",
  "mcnId": "7000000000000000001",
  "joinedAt": "2021-05-12T00:00:00Z",
  "updatedAt": "2026-10-10T00:00:00Z",
  "price20To60s": 13000,
  "price60sPlus": 15000,
  "medianPlays": 310000,
  "averageLikes": 4800,
  "averageComments": 120,
  "averageShares": 1100,
  "averageVideoSeconds": 48.5,
  "interactionRate": 0.0168,
  "playCompletionRate": 0.2,
  "expectedCpm20To60s": 33.33,
  "expectedCpe20To60s": 1.88,
  "salesExpectedCpm20To60s": 30.1,
  "selfIntroduction": "...",
  "creditScore": 95,
  "cooperationBrands": null,
  "email": null,
  "wechat": null,
  "hasWechat": false,
  "audience": {
    "age": [{"label": "41-50", "count": 116000, "share": 6.43}],
    "gender": [{"label": "female", "count": 1050000, "share": 58.2}],
    "province": [], "city": [], "cityTier": [], "deviceBrand": [], "interest": [], "crowd": []
  }
}
```

#### Ranking row (`rankedCreator`)

```json
{
  "type": "rankedCreator",
  "userId": "6800000000000000002",
  "url": "https://www.xingtu.cn/ad/creator/author-homepage/douyin-video/6800000000000000002",
  "nickname": "示例美妆达人",
  "followers": 860000,
  "rank": 3,
  "previousRank": 7,
  "isNew": false,
  "score": 91.2,
  "primaryCategory": "美妆",
  "averagePlays": 420000,
  "cpm": 28.5,
  "completedOrders": "> 20",
  "repurchaseRate": "> 0.75",
  "orderRate": 0.32,
  "followersGained": null,
  "videoCount": null,
  "price20To60s": null,
  "recentVideos": []
}
```

### How much does it cost?

The Actor uses pay-per-event pricing. These are the current prices:

| Event | Price | When it is charged |
|---|---|---|
| Run start | $0.005 | Once per run, when the first request to the data source succeeds, even if that request returns nothing. Not charged when the data source fails from the start or rejects the IDs, or when your spending limit cannot cover it |
| Result | $0.01 | Per creator from a search, or per ranking row |
| Detail | $0.04 | Per full creator profile (mode `creator`) |

Worked examples:

- 100 creators from a search: $0.005 + 100 x $0.01 = $1.005.
- One ranking with 100 rows: $0.005 + 100 x $0.01 = $1.005.
- 10 full creator profiles: $0.005 + 10 x $0.04 = $0.405.

You never pay for more than `maxResults` items, items that were not delivered are never charged, and the run stops by itself if your spending limit is reached.

On the free Apify plan, a run returns at most 20 results and covers at most one creator profile or one ranking. Any paid Apify plan removes the limit. On the free Apify plan each account can run this Actor up to 3 times per 24 hours and 10 times per 7 days, within a small lifetime free allowance shared across all our Actors, and all free accounts share a daily free budget. When any of these limits is reached, the run stops before fetching anything and nothing is charged.

### Use cases

- Influencer sourcing: shortlist Douyin creators in a category within a follower range and budget, with their video quotes (`price20To60s`, `price60sPlus`).
- Campaign planning: compare expected CPM and CPE across creators and video lengths before you book a brand deal.
- Audience checks: confirm that a creator's audience matches your target by age, gender, province, city tier, device brand and interests.
- Market monitoring: follow the weekly and monthly rankings of your industry and spot rising creators early with `rank`, `previousRank` and `isNew`.
- Agency and sales research: see which agency (MCN) a creator belongs to and which brands they list as past partners.
- E-commerce partner search: find creators who sell products using `ecommerceEnabled`, `ecommerceLevel` and `ecommerceGmv30dRange`.

### Integrations and API

You can start runs through the Apify API, schedule them (for example every Monday to catch the new weekly ranking), and connect the results to Apify integrations such as webhooks, Google Sheets or Make. Here is a Python example with the `apify-client` package:

```python
from apify_client import ApifyClient
client = ApifyClient("<YOUR_APIFY_TOKEN>")
run = client.actor("clover_folktale/xingtu-scraper").call(run_input={
    "mode": "ranking",
    "rankingList": "rising-stars",
    "rankingPeriod": "weekly",
    "rankingCategory": "food",
    "maxResults": 100
})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)
```

A common workflow is to run a search or ranking first, then pass the `userId` values to mode `creator` to get full profiles with audience data.

### Tips and limits

- `maxResults` is the total across all creators in the run; a run stops as soon as it is reached.
- A search page holds up to 20 creators; a ranking request returns up to 100.
- Use `searchBy: "content"` to find creators by what their videos are about instead of by name.
- The `userId` of a search or ranking row is the ID to give mode `creator`.
- Rankings read the latest published edition; set `rankingDate` (YYYYMMDD, the last day of the period) for an earlier one.
- Industry rankings (brand preferred, A3 seeding, search after view, e-commerce, ad traffic, high potential) take an industry category such as `electronics` or `beauty`; rising stars and top picks take a content category such as `food` or `travel`.
- A ranking category a list does not publish (for example an auto ranking for the e-commerce list) returns no results; only the $0.005 run start is charged.
- Creator IDs that do not exist are skipped and not charged; if too many inputs return nothing, the run stops to protect your budget.
- The Actor retries transient errors and empty pages on its own and stops cleanly instead of failing half-way.
- Quotes are in Chinese yuan (CNY). Rates such as `interactionRate30d` are fractions (0.0174 = 1.74%). Audience `share` values are in percent.
- Figures are what Xingtu shows at the time of the run; rankings update weekly or monthly.
- On the free Apify plan a run returns at most 20 results and covers at most one creator profile or one ranking.

#### Fields that are often empty

- `price20To60s` and `price60sPlus` are `null` when a creator does not sell that video length.
- `email`, `wechat` and `cooperationBrands` are empty unless the creator filled them in.
- Ranking rows carry fewer fields than search rows: no quotes, expected plays, CPM/CPE, indexes, e-commerce figures or recent videos (those are `null` or empty). Take them from a search or a profile.
- The figures a list adds (average plays, CPM, follower gain, order figures) depend on the list.
- `ecommerceLevel` and `ecommerceGmv30dRange` are `null` for creators who do not sell products.
- `recentVideos` can be empty for new creators.
- Single `audience` kinds can be missing for creators with few followers.

### FAQ

#### Do I need a Douyin or Xingtu account?

No. You do not need a Douyin account, API keys, proxies or cookies.

#### Is it legal to scrape Xingtu?

The Actor returns only data that Xingtu itself publishes about creators: creator IDs, names, avatars, location, quotes, performance figures, audience statistics and the business contact details a creator chose to publish for brands. Phone numbers are masked by the platform and not returned, and no private messages are collected. You are responsible for how you use the data, including compliance with data-protection laws in your country.

#### How fresh is the data?

Every run reads the figures Xingtu shows at that moment. Rankings are published weekly or monthly; use `rankingDate` to read an earlier edition.

#### Why are some fields empty?

Some data only exists for some creators (for example quotes for one video length, e-commerce figures, or contact details), and ranking rows carry fewer fields than search rows. See Fields that are often empty above.

#### How many results can I get?

Up to 5,000 items per run with `maxResults`. A search page holds up to 20 creators and a ranking request returns up to 100. On the free Apify plan a run returns at most 20 results and covers at most one creator profile or one ranking.

#### Can I schedule runs and export the data?

Yes. You can schedule runs in Apify Console or start them through the API, and export every dataset as JSON, CSV or Excel.

#### A field or mode I need is missing. What can I do?

Open an issue from the Actor page and it will be looked at.

### More tools from the same developer

- [Douyin 抖音 Scraper - Videos, Comments, User IDs & IP Location](https://apify.com/clover_folktale/douyin-scraper)
- [Douyin Shop 抖音商城 Scraper - Products, Sales, Commission](https://apify.com/clover_folktale/douyin-shop-scraper)
- [Xiaohongshu Pugongying 蒲公英 Scraper - KOL Search](https://apify.com/clover_folktale/pugongying-scraper)
- [Bilibili Huahuo 花火 Scraper - KOL (UP Host) Search](https://apify.com/clover_folktale/huahuo-scraper)
- [Xiaohongshu 小红书 RedNote Scraper - Notes, Comments & User IP](https://apify.com/clover_folktale/xiaohongshu-scraper)
- [TikTok Scraper - Video Search, Hashtags & Author Profiles](https://apify.com/clover_folktale/tiktok-scraper)

# Actor input Schema

## `mode` (type: `string`):

What to scrape: creators matching a search, full profiles of given creators, or an official ranking list.

## `keyword` (type: `string`):

Creator nickname or, with searchBy = content, a topic found in the creators' videos. Optional: leave empty to browse creators with the filters below only.

## `searchBy` (type: `string`):

Match the keyword against creator nicknames or against the content of their videos.

## `category` (type: `string`):

Only creators in this category.

## `gender` (type: `string`):

Only male or female creators.

## `minFollowers` (type: `integer`):

Only creators with at least this many followers.

## `maxFollowers` (type: `integer`):

Only creators with at most this many followers.

## `sort` (type: `string`):

Best match first, or by follower count.

## `creators` (type: `array`):

Xingtu creator IDs (the long number returned as userId by the search) or Xingtu creator page links, e.g. https://www.xingtu.cn/ad/creator/author-homepage/douyin-video/6839869628747874312.

## `rankingList` (type: `string`):

Which official ranking to read. The list ranks creators by their commercial results or growth.

## `rankingPeriod` (type: `string`):

Weekly or monthly edition. The latest published edition is read unless you give a date.

## `rankingCategory` (type: `string`):

Advertiser industry (lists brand-preferred, a3-seeding, search-after-view, ecommerce, ad-traffic, high-potential) or content category (rising-stars, top-picks). Leave unset for the default of the chosen list. A category a list does not publish returns no results.

## `rankingDate` (type: `string`):

Optional edition to read, as YYYYMMDD: the last day of the period, e.g. 20260930 for the September 2026 monthly edition. Empty reads the latest edition.

## `maxResults` (type: `integer`):

Maximum number of items to return in total for this run. You are charged per item returned. On the free Apify plan a run returns at most 20 results in total; any paid Apify plan removes the limit.

## Actor input object example

```json
{
  "mode": "search",
  "searchBy": "nickname",
  "category": "any",
  "gender": "any",
  "sort": "relevance",
  "creators": [
    "6839869628747874312"
  ],
  "rankingList": "brand-preferred",
  "rankingPeriod": "monthly",
  "maxResults": 20
}
```

# Actor output Schema

## `results` (type: `string`):

All scraped items (JSON, CSV, Excel via the dataset API).

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "creators": [
        "6839869628747874312"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("clover_folktale/xingtu-scraper").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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "creators": ["6839869628747874312"] }

# Run the Actor and wait for it to finish
run = client.actor("clover_folktale/xingtu-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "creators": [
    "6839869628747874312"
  ]
}' |
apify call clover_folktale/xingtu-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,clover_folktale/xingtu-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/663VcoJQGOIMQOTqD/builds/j3b1T3Re9NrhWFGsq/openapi.json