# Kugou Music Scraper: 酷狗音乐 Catalog, Charts & Lyrics (`getascraper/kugou-music-scraper`) Actor

Scrape Kugou Music (酷狗音乐) song search, album and artist catalogs, chart rankings (30-min refresh cadence), full playlist tracklists, and timed lyrics. No login, no signature - direct legacy JSON API. Comments are not yet supported (Phase 2, deferred).

- **URL**: https://apify.com/getascraper/kugou-music-scraper.md
- **Developed by:** [GetAScraper](https://apify.com/getascraper) (community)
- **Categories:** Social media, Automation
- **Stats:** 2 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.10 / 1,000 music records

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/docs.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.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/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

## Kugou Music Scraper: 酷狗音乐 Catalog, Charts & Lyrics

<table width="100%">
<tr>
<td style="padding:24px 28px;background:#FDF2F8;border:1px solid #F4B8D3;border-top:4px solid #9D174D;border-radius:12px">
<span style="font-size:23px;font-weight:800;color:#1C1917;line-height:1.3">Kugou Music data on demand: songs, charts, playlists and lyrics.</span><br>
<span style="font-size:15px;color:#57534E;line-height:1.6">Look up any song, album or artist on Kugou (酷狗音乐), pull full playlist tracklists, or watch a chart update every 30 minutes, automatically, with no account required.</span>
</td>
</tr>
</table>

<table width="100%">
<tr>
<td style="padding:14px 12px;width:25%;background:#FFFFFF;border:1px solid #F4B8D3;border-radius:10px 0 0 10px;vertical-align:top">
<span style="font-size:15px;font-weight:800;color:#831843">🔍 Full catalog search</span><br>
<span style="font-size:12px;color:#57534E">Song, album and artist lookups with cover art, release date and audio quality tiers</span>
</td>
<td style="padding:14px 12px;width:25%;background:#FFFFFF;border:1px solid #F4B8D3;border-left:none;vertical-align:top">
<span style="font-size:15px;font-weight:800;color:#831843">🏆 Live chart tracking</span><br>
<span style="font-size:12px;color:#57534E">All 55 official charts and their ranked songs, refreshed on Kugou's own 30-minute cycle</span>
</td>
<td style="padding:14px 12px;width:25%;background:#FFFFFF;border:1px solid #F4B8D3;border-left:none;vertical-align:top">
<span style="font-size:15px;font-weight:800;color:#831843">📋 Complete playlists</span><br>
<span style="font-size:12px;color:#57534E">Search playlists by keyword or pull a full tracklist, creator and play count included</span>
</td>
<td style="padding:14px 12px;width:25%;background:#FFFFFF;border:1px solid #F4B8D3;border-left:none;border-radius:0 10px 10px 0;vertical-align:top">
<span style="font-size:15px;font-weight:800;color:#831843">🎤 Timed lyrics included</span><br>
<span style="font-size:12px;color:#57534E">Full time-stamped lyrics for any song, ready for subtitles or karaoke tools</span>
</td>
</tr>
</table>

Give this Actor a keyword or an ID and it returns structured Kugou data in seconds: song search results, a full album or artist catalog, a playlist tracklist, a chart snapshot, or timed lyrics. Built for music-industry researchers tracking Chinese catalog and chart trends, marketing teams watching what's climbing the playlists this week, and developers who want clean Kugou data without digging through the app by hand. Runs on the Apify platform with scheduling, integrations (Make, Zapier, Google Sheets), and run monitoring built in.

### 🔍 What does Kugou Music Scraper do?

This Actor reads public catalog data from [Kugou Music](https://www.kugou.com) (酷狗音乐), one of China's largest music streaming platforms, part of the Tencent Music Entertainment family.

Pick one of eight modes per run: search songs by keyword, pull a full album tracklist by ID, get an artist's complete catalog plus biography, search playlists by keyword, pull a full playlist tracklist by ID, list all 55 official Kugou charts, snapshot the ranked songs on any one chart, or fetch full time-stamped lyrics for a song. Every mode returns clean, structured rows, ready to download or send to your own system. A field a specific song or album doesn't have (no high-resolution audio tier, no music video, no album name on some lookups) is simply left out of that row rather than filled in with a placeholder.

**A note on comments:** this Actor does not return song, album or playlist comments. Comment threads sit behind a much stricter verification wall on Kugou's platform than the catalog, chart and lyrics data covered here. Reliable comment support is a bigger, separate project we're tracking based on demand for this Actor first, not something bolted on halfway.

### 💡 Why use Kugou Music Scraper?

- **I track Chinese music trends for licensing or A&R** and need real catalog depth and chart movement for an artist or genre on one of China's largest platforms, without hiring a local researcher.
- **I monitor playlist culture and marketing trends** and want to know what's actually climbing the charts and showing up in playlists this week, sourced straight from Kugou's own numbers.
- **I'm building a music app or dataset** and need structured song, album and lyric data for Kugou, ready to drop into my own product without reverse-engineering the platform myself.
- **I run a scheduled chart-monitoring job** and want a feed that updates itself, timed to match how often Kugou's own charts actually refresh.

### 🚀 How to use Kugou Music Scraper

<table width="100%">
<tr>
<td style="padding:16px 14px;width:33%;background:#FDF2F8;border:1px solid #F4B8D3;border-radius:10px 0 0 10px;vertical-align:top">
<span style="font-size:12px;font-weight:800;color:#9D174D;letter-spacing:1px">STEP 1</span><br>
<span style="font-size:14px;font-weight:700;color:#1C1917">Pick a mode</span><br>
<span style="font-size:12px;color:#57534E">Song search, album, artist, playlist, chart, or lyrics.</span>
</td>
<td style="padding:16px 14px;width:33%;background:#FDF2F8;border:1px solid #F4B8D3;border-left:none;vertical-align:top">
<span style="font-size:12px;font-weight:800;color:#9D174D;letter-spacing:1px">STEP 2</span><br>
<span style="font-size:14px;font-weight:700;color:#1C1917">Enter a keyword or ID</span><br>
<span style="font-size:12px;color:#57534E">Search by name, or paste an ID from a previous run.</span>
</td>
<td style="padding:16px 14px;width:33%;background:#FDF2F8;border:1px solid #F4B8D3;border-left:none;border-radius:0 10px 10px 0;vertical-align:top">
<span style="font-size:12px;font-weight:800;color:#9D174D;letter-spacing:1px">STEP 3</span><br>
<span style="font-size:14px;font-weight:700;color:#1C1917">Export your results</span><br>
<span style="font-size:12px;color:#57534E">Download as JSON, CSV or Excel, or send it to your own system.</span>
</td>
</tr>
</table>

### ⚙️ Input

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `mode` | enum | No | `songSearch`, `albumTracklist`, `artistCatalog`, `playlistSearch`, `playlistTracklist`, `chartIndex`, `chartSnapshot`, or `lyrics`. Defaults to `songSearch`. |
| `query` | string | No | Search keyword. Used by Song search and Playlist search (any keyword) and Lyrics mode (works best as "singer song title", e.g. "周杰伦 晴天"). |
| `albumId` | string | No | Kugou album ID. Used by Album tracklist mode. |
| `singerId` | string | No | Kugou singer/artist ID. Used by Artist catalog mode. |
| `specialId` | string | No | Kugou playlist ID. Used by Playlist tracklist mode. |
| `rankId` | string | No | Kugou chart ID. Defaults to `8888` (TOP500). Used by Chart snapshot mode; run Chart index mode first to see all chart IDs and names. |
| `maxItems` | integer | No | Maximum number of records to fetch and push in this run. Defaults to `50`. |
| `proxyConfiguration` | object | No | Proxy routing settings. Defaults to Apify's standard proxy, which this target works reliably with. |

### 📦 Output

Download the results as a spreadsheet, a table, or structured data ready for your own systems. A song row from Song search mode looks like this:

```json
{
  "recordType": "song",
  "sourceMode": "songSearch",
  "scrapedAt": "2026-07-19T00:00:00.000Z",
  "songId": "8AC4F90B1E3DF716D216D74223016E17",
  "songName": "千山万水",
  "singerName": "周杰伦",
  "singerId": "3520",
  "albumId": "2606360",
  "albumName": "北京2008年奥运会歌曲专辑",
  "durationSec": 247,
  "publishDate": "2008-05-02",
  "coverUrl": "http://imge.kugou.com/stdmusic/480/20250125/20250125121629695890.jpg",
  "isPaid": false,
  "hash128": "8AC4F90B1E3DF716D216D74223016E17",
  "hash320": "5BFD0161C4BE57FA4C355B76386233EF",
  "hashFlac": "6C5C7B66CEBA518DA71FDA7EA2E4559A",
  "songPageUrl": "https://www.kugou.com/mixsong/64574642.html"
}
````

A chart snapshot row, a playlist row, an artist bio row and a lyrics row each carry their own set of fields, described in full below. Every mode shares the same `recordType` and `sourceMode` fields so you can tell rows apart when combining runs.

### 📊 Output data fields

| Field | Type | Description |
| --- | --- | --- |
| `recordType` | string | `song`, `chart`, `playlist`, `artist`, or `lyrics`. Tells you which field group below applies to a given row. |
| `sourceMode` | string | Which run mode produced this row. |
| `scrapedAt` | string | Timestamp when this row was collected. |
| `songId`, `songName`, `singerName`, `singerId` | string | Core song identity, present on every `song` row. |
| `albumId` / `albumName` | string | Album identity, when the source data includes it. |
| `durationSec` | number | Track length in seconds. |
| `publishDate` | string | Release date, when published. |
| `coverUrl` | string | Cover art image link. |
| `isPaid` / `payType` | boolean / number | Whether the track requires a paid or VIP tier to stream. |
| `hash128`, `hash320`, `hashFlac` | string | Kugou's own identifiers for the standard, high, and lossless audio quality tiers available for the track. |
| `position` | number | Chart rank or track order, when the source data provides one. |
| `songPageUrl` | string | Direct link to the song's page on kugou.com, when available. |
| `chartId`, `chartName`, `chartRefreshCadenceSec`, `chartUpdateFrequencyText`, `chartItemCount`, `chartIntro`, `chartCoverUrl` | string / number | Chart identity and metadata, present on `chart` rows and attached to `song` rows from Chart snapshot mode. `chartRefreshCadenceSec` is Kugou's own stated refresh interval (1800 seconds / 30 minutes for most charts). |
| `playlistId`, `playlistName`, `playlistCreator`, `playlistPlayCount`, `playlistSongCount`, `playlistPublishTime`, `playlistCoverUrl` | number / string | Playlist identity and stats, present on `playlist` rows. |
| `artistId`, `artistName`, `artistBio`, `artistSongCount`, `artistAvatarUrl` | string / number | Artist biography fields, present on the one `artist` row an Artist catalog run returns. |
| `lyricsId`, `lyricsAccessKey`, `lyricsSinger`, `lyricsSong`, `lyricsContent`, `lyricsSource`, `lyricsScore` | string / number | Timed lyrics text and match metadata, present on `lyrics` rows. `lyricsContent` is the full time-stamped lyric text. |
| `engagementTag` | string | A short popularity tag Kugou attaches to some search results, when present. |
| `sourceQuery` | string | The search keyword that produced this row, when the mode is keyword-based. |
| `sourceUrl` | string | The Kugou data source this row was collected from. |

### 💰 Pricing

This Actor uses pay-per-result pricing: you pay for the records you actually get back, and nothing for an empty run. There is no subscription and no minimum spend. Use `maxItems` to control how many results a run returns.

### ⭐ Enjoying Kugou Music Scraper: 酷狗音乐 Catalog, Charts & Lyrics?

<table width="100%">
<tr>
<td style="padding:20px 24px 14px;background:#FDF2F8;border:1px solid #F4B8D3;border-left:5px solid #9D174D;border-radius:10px 10px 0 0">
<span style="font-size:20px;letter-spacing:4px">⭐ ⭐ ⭐ ⭐ ⭐</span><br>
<span style="font-size:17px;font-weight:800;color:#1C1917">Found a hit before it topped the charts?</span><br>
<span style="font-size:14px;color:#57534E">A 5-star rating takes 10 seconds and helps other music researchers, marketers, and developers tracking Chinese platforms find this Actor. Your feedback also tells us what to build next.</span>
</td>
</tr>
<tr>
<td style="padding:0;background:#9D174D;border:1px solid #F4B8D3;border-top:none;border-radius:0 0 10px 10px;text-align:center">
<a href="https://apify.com/getascraper/kugou-music-scraper/reviews" style="display:block;padding:13px 16px;color:#FFFFFF;text-decoration:none;font-weight:800;font-size:15px;letter-spacing:0.3px">★&nbsp;&nbsp;Rate this Actor on Apify</a>
</td>
</tr>
</table>

### ✨ Tips

- Run Song search or Playlist search first to discover the IDs you need for Album tracklist, Artist catalog, and Playlist tracklist modes.
- Run Chart index mode once to see all 55 official chart IDs and names, then use the one you want in Chart snapshot mode.
- Schedule Chart snapshot mode on a 30-minute interval in the Apify Console to match Kugou's own chart refresh cycle for a self-updating trend feed.
- For Lyrics mode, "singer song title" (either script) matches better than the song title alone, since Kugou indexes lyrics by both.
- A missing `albumName` on some song rows is expected: a few Kugou lookups return the album ID but not a separate album name field.

### ❓ FAQ, disclaimers, and support

**如何获取酷狗音乐的歌词数据？** Set `mode` to `lyrics` and enter a singer and song title in `query` (e.g. "周杰伦 晴天"). The Actor returns the matching candidates with full time-stamped lyric text for each.

**酷狗音乐排行榜多久更新一次？** Kugou's own charts report a 30-minute refresh cycle for most rankings. Run Chart index mode to see each chart's exact cadence, then schedule Chart snapshot mode at that interval for a self-updating feed.

**Does this Actor return song, album or playlist comments?** Not yet. Comments live behind a much stricter verification wall on Kugou's platform than the catalog, chart and lyrics data this Actor covers. Reliable comment support is a bigger, separate project we're tracking based on demand for this Actor first.

**Do I need a Kugou account or login?** No. Every mode in this Actor reads publicly available catalog data with no sign-in required.

**How fresh is the data?** Every run reads current data directly from Kugou at run time. There is no cached or stale data.

**Is scraping Kugou data legal?** This Actor collects publicly available catalog, chart, playlist and lyrics data. You are responsible for complying with Kugou's Terms of Service and applicable laws in your use of the data.

**Found a bug or need a field added?** Open an issue on the Actor's **Issues** tab. Custom solutions are available on request.

### 🔗 Other actors

- [Xigua Video Search Scraper: Keyword, Comments & Video Links](https://apify.com/getascraper/xigua-video-search-scraper) ↗ - pulls search results, comments and video links from another major Chinese content platform.
- [Buyee Scraper: Yahoo Auctions & Mercari Japan Data](https://apify.com/getascraper/buyee-scraper) ↗ - structured listing data from Japan's largest cross-border auction and marketplace proxy.
- [Viewstats YouTube Analytics & Rankings Scraper](https://apify.com/getascraper/viewstats-scraper) ↗ - channel and video analytics for tracking what's trending on YouTube.
- [Twitch Scraper: channels, live streams, clips and games](https://apify.com/getascraper/twitch-scraper) ↗ - live stream, clip and channel data for media monitoring.
- [Google Lens OCR API](https://apify.com/getascraper/google-lens-ocr) ↗ - a fast, agent-friendly text and object recognition utility.

# Actor input Schema

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

Song search, album tracklist, artist catalog + bio, playlist search, playlist tracklist, chart index, chart snapshot, or lyrics. Comments are NOT supported - see the README for why.

## `query` (type: `string`):

For Song search / Playlist search: any keyword, e.g. "周杰伦" or "流行". For Lyrics: "singer song title" works best, e.g. "周杰伦 晴天" or "Jay Chou Sunny Day" - the closer to Kugou's own "Singer - Song" naming, the better the match.

## `albumId` (type: `string`):

Kugou album ID, e.g. 2606360. Only used in Album tracklist mode.

## `singerId` (type: `string`):

Kugou singer ID, e.g. 3520 (周杰伦 / Jay Chou). Only used in Artist catalog mode.

## `specialId` (type: `string`):

Kugou playlist ("special") ID, e.g. 9180602. Only used in Playlist tracklist mode.

## `rankId` (type: `string`):

Kugou chart ("rank") ID. Defaults to 8888 (TOP500). Run Chart index mode first to see all 55 chart IDs and names. Only used in Chart snapshot mode. Kugou's own chart-index API reports a 1800-second (30-minute) official refresh cadence - schedule this mode at that interval in the Apify Console for a recurring chart-monitor run.

## `maxItems` (type: `integer`):

Maximum number of records to fetch and push in this run (songs, charts, playlists, or lyrics candidates depending on mode).

## `proxyConfiguration` (type: `object`):

Kugou's legacy API showed zero WAF/bot-management signature, zero TLS fingerprint gate, and a clean 10/10 burst test during this Actor's build-time recon - Datacenter proxy is the default and is expected to work reliably. Switch to Residential only if you see repeated request failures.

## Actor input object example

```json
{
  "mode": "songSearch",
  "query": "周杰伦 晴天",
  "albumId": "2606360",
  "singerId": "3520",
  "specialId": "9180602",
  "rankId": "8888",
  "maxItems": 50,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `records` (type: `string`):

No description

# 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 = {
    "query": "周杰伦",
    "rankId": "8888",
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("getascraper/kugou-music-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 = {
    "query": "周杰伦",
    "rankId": "8888",
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("getascraper/kugou-music-scraper").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 '{
  "query": "周杰伦",
  "rankId": "8888",
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call getascraper/kugou-music-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=getascraper/kugou-music-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Kugou Music Scraper: 酷狗音乐 Catalog, Charts & Lyrics",
        "description": "Scrape Kugou Music (酷狗音乐) song search, album and artist catalogs, chart rankings (30-min refresh cadence), full playlist tracklists, and timed lyrics. No login, no signature - direct legacy JSON API. Comments are not yet supported (Phase 2, deferred).",
        "version": "0.1",
        "x-build-id": "HHF0GMFS5a6uJGr4L"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/getascraper~kugou-music-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-getascraper-kugou-music-scraper",
                "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/getascraper~kugou-music-scraper/runs": {
            "post": {
                "operationId": "runs-sync-getascraper-kugou-music-scraper",
                "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/getascraper~kugou-music-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-getascraper-kugou-music-scraper",
                "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",
                "properties": {
                    "mode": {
                        "title": "Mode",
                        "enum": [
                            "songSearch",
                            "albumTracklist",
                            "artistCatalog",
                            "playlistSearch",
                            "playlistTracklist",
                            "chartIndex",
                            "chartSnapshot",
                            "lyrics"
                        ],
                        "type": "string",
                        "description": "Song search, album tracklist, artist catalog + bio, playlist search, playlist tracklist, chart index, chart snapshot, or lyrics. Comments are NOT supported - see the README for why.",
                        "default": "songSearch"
                    },
                    "query": {
                        "title": "Search keyword",
                        "type": "string",
                        "description": "For Song search / Playlist search: any keyword, e.g. \"周杰伦\" or \"流行\". For Lyrics: \"singer song title\" works best, e.g. \"周杰伦 晴天\" or \"Jay Chou Sunny Day\" - the closer to Kugou's own \"Singer - Song\" naming, the better the match."
                    },
                    "albumId": {
                        "title": "Album ID (Album tracklist mode)",
                        "type": "string",
                        "description": "Kugou album ID, e.g. 2606360. Only used in Album tracklist mode."
                    },
                    "singerId": {
                        "title": "Singer/artist ID (Artist catalog mode)",
                        "type": "string",
                        "description": "Kugou singer ID, e.g. 3520 (周杰伦 / Jay Chou). Only used in Artist catalog mode."
                    },
                    "specialId": {
                        "title": "Playlist ID (Playlist tracklist mode)",
                        "type": "string",
                        "description": "Kugou playlist (\"special\") ID, e.g. 9180602. Only used in Playlist tracklist mode."
                    },
                    "rankId": {
                        "title": "Chart ID (Chart snapshot mode)",
                        "type": "string",
                        "description": "Kugou chart (\"rank\") ID. Defaults to 8888 (TOP500). Run Chart index mode first to see all 55 chart IDs and names. Only used in Chart snapshot mode. Kugou's own chart-index API reports a 1800-second (30-minute) official refresh cadence - schedule this mode at that interval in the Apify Console for a recurring chart-monitor run.",
                        "default": "8888"
                    },
                    "maxItems": {
                        "title": "Max items",
                        "minimum": 1,
                        "type": "integer",
                        "description": "Maximum number of records to fetch and push in this run (songs, charts, playlists, or lyrics candidates depending on mode).",
                        "default": 50
                    },
                    "proxyConfiguration": {
                        "title": "Proxy configuration",
                        "type": "object",
                        "description": "Kugou's legacy API showed zero WAF/bot-management signature, zero TLS fingerprint gate, and a clean 10/10 burst test during this Actor's build-time recon - Datacenter proxy is the default and is expected to work reliably. Switch to Residential only if you see repeated request failures.",
                        "default": {
                            "useApifyProxy": true
                        }
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```
