# Spotify Scraper (`unfenced-group/spotify-scraper`) Actor

Scrape Spotify albums, tracks, artists and playlists with full metadata: popularity, genres, available markets, ISRC/UPC, followers, tracklists, cover art and audio previews. Works out of the box; add free Spotify API credentials for keyword search and complete metadata.

- **URL**: https://apify.com/unfenced-group/spotify-scraper.md
- **Developed by:** [Unfenced Group](https://apify.com/unfenced-group) (community)
- **Categories:** E-commerce
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.19 / 1,000 results

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

## Spotify Scraper
![Banner](https://api.apify.com/v2/key-value-stores/lJlifu6C8YQfZMPKE/records/spotify-scraper)

Scrape Spotify albums, tracks, artists and playlists with full metadata — popularity, genres, available markets, ISRC/UPC codes, follower counts, full tracklists, cover art and audio previews. Works out of the box for any Spotify URL. Add free Spotify API credentials to unlock keyword search and complete metadata.

---

### Two ways to run

#### Embed mode — no setup
Paste any Spotify URL or URI (album, track, artist or playlist) and the scraper returns its core metadata immediately. No account, no credentials, no configuration. Keyword search is not available in this mode.

#### API mode — free credentials, full power
Add a Spotify Client ID and Client Secret (free, two minutes to create) and the scraper unlocks:
- **Keyword search** across albums, tracks, artists and playlists
- **Popularity** scores, **genres**, **follower** counts
- **Available markets** per item, **ISRC** (tracks) and **UPC** (albums) codes
- **Record label**, **copyrights**, release-date precision
- Full **tracklists** for albums and playlists with per-track metadata
- Artist to discography expansion

Both modes use the same flat per-result pricing.

---

### How to get free Spotify API credentials

1. Go to the Spotify Developer Dashboard at developer.spotify.com/dashboard and log in with any Spotify account.
2. Click **Create app**. Give it any name and description. For the redirect URI you can enter `https://localhost` (it is not used by this scraper).
3. Open the app, then **Settings**. Copy the **Client ID** and **Client Secret**.
4. Paste them into the `clientId` and `clientSecret` fields below.

The credentials are stored encrypted and used only to request a read-only catalogue token. No user login or personal data is involved.

---

### Why this scraper?

#### Artist stats the official API can't give you
Turn on artist stats and every artist returns monthly listeners, world rank, follower count, top listener cities (with per-city listener numbers), top tracks with exact play counts, biography, verified status and related artists. These are the figures the Spotify app shows and the official Web API does not expose. No credentials needed — works in both modes.

#### Most fields on the platform
Popularity, genres, markets, ISRC/UPC, label, copyrights, followers, tracklists, cover art in every size, and audio previews — the full Spotify catalogue object, not a thin subset.

#### Real keyword search
Search the entire Spotify catalogue by keyword across four entity types in one run.

#### Full tracklists
Albums and playlists return every track with title, artists, duration, explicit flag, ISRC, popularity and preview URL.

#### Market-aware
Pick any Spotify market to get accurate availability and playability, and see every market an item is available in.

#### Pay only for results
Flat per-item pricing. You only pay for items actually returned. Filtered-out items and failed retries are never charged.

---

### Input parameters

| Field | Type | Default | Description |
|---|---|---|---|
| `searchQuery` | string | `""` | Keyword(s) to search Spotify. Requires API credentials. |
| `entityTypes` | array | `["album","track"]` | What to search for: `album`, `track`, `artist`, `playlist`. |
| `startUrls` | array | `[]` | Spotify URLs or URIs to scrape directly. Works in both modes. |
| `spotifyIds` | array | `[]` | Spotify IDs or URIs. URIs (`spotify:album:ID`) are preferred over bare IDs. |
| `maxResults` | integer | `10` | Maximum number of items to return. |
| `market` | string | `US` | ISO market for availability and catalogue (API mode). |
| `includeTracklist` | boolean | `false` | Fetch full tracklists for albums and playlists (API mode). |
| `expandArtistAlbums` | boolean | `false` | Also scrape an artist's albums and singles (API mode). |
| `includeArtistStats` | boolean | `false` | For artists, fetch monthly listeners, world rank, top cities, top tracks with play counts, biography and related artists. Both modes, no credentials. |
| `filterTypes` | array | `[]` | Keep only these types in the output. |
| `explicitFilter` | string | `all` | `all`, `clean`, or `explicit`. |
| `genres` | array | `[]` | Filter by genre (substring match). |
| `minPopularity` | integer | - | Only items with popularity (0-100) at least this value. |
| `releasedAfter` | string | `""` | Only items released on or after this date (YYYY-MM-DD). |
| `releasedBefore` | string | `""` | Only items released on or before this date (YYYY-MM-DD). |
| `includeMedia` | boolean | `true` | Include cover art and audio preview URLs. |
| `clientId` | string | `""` | Spotify app Client ID (enables API mode). |
| `clientSecret` | string (secret) | - | Spotify app Client Secret. Stored encrypted. |
| `useProxy` | boolean | `false` | Route requests through Apify Proxy. |

---

### Output schema

Fields vary by entity type and by mode. API mode returns the full set; embed mode returns the core subset. Every item carries `type`, `id`, `uri`, `name`, `artistName`, `spotifyUrl`, `source` (`api` or `embed`) and `scrapedAt`.

#### Album
`albumType`, `artists[]`, `releaseDate`, `releaseDatePrecision`, `totalTracks`, `label`, `genres[]`, `popularity`, `upc`, `copyrights[]`, `availableMarkets[]`, `marketCount`, `images[]`, `coverUrl`, and `tracks[]` when tracklists are enabled.

#### Track
`artists[]`, `albumId`, `albumName`, `albumType`, `releaseDate`, `trackNumber`, `discNumber`, `durationMs`, `durationSec`, `explicit`, `popularity`, `isrc`, `previewUrl`, `isPlayable`, `availableMarkets[]`, `marketCount`, `images[]`, `coverUrl`.

#### Artist
`genres[]`, `popularity`, `followers`, `images[]`, `coverUrl`. With `includeArtistStats` on, also: `monthlyListeners`, `worldRank`, `verified`, `biography`, `topCities[]` (city, country, region, listeners), `topTracks[]` (name, uri, playcount), `relatedArtists[]`, `albumCount`, `singleCount`.

#### Playlist
`description`, `owner`, `isPublic`, `collaborative`, `followers`, `totalTracks`, `images[]`, `coverUrl`, and `tracks[]` when tracklists are enabled.

#### Example track (API mode)

```json
{
  "type": "track",
  "id": "0VjIjW4GlUZAMYd2vXMi3b",
  "uri": "spotify:track:0VjIjW4GlUZAMYd2vXMi3b",
  "name": "Blinding Lights",
  "artists": [{ "id": "1Xyo4u8uXC1ZmMpatF05PJ", "name": "The Weeknd" }],
  "artistName": "The Weeknd",
  "albumName": "After Hours",
  "trackNumber": 9,
  "durationSec": 200,
  "explicit": false,
  "popularity": 92,
  "isrc": "USUG11904206",
  "previewUrl": "https://p.scdn.co/mp3-preview/...",
  "marketCount": 184,
  "coverUrl": "https://i.scdn.co/image/...",
  "spotifyUrl": "https://open.spotify.com/track/0VjIjW4GlUZAMYd2vXMi3b",
  "source": "api"
}
````

***

### Examples

**1. Search tracks by keyword (API mode)**

```json
{
  "searchQuery": "the weeknd",
  "entityTypes": ["track"],
  "market": "US",
  "maxResults": 20,
  "clientId": "your_client_id",
  "clientSecret": "your_client_secret"
}
```

**2. Scrape an album with its full tracklist**

```json
{
  "startUrls": ["https://open.spotify.com/album/4yP0hdKOZPNshxUOjY0cZj"],
  "includeTracklist": true,
  "clientId": "your_client_id",
  "clientSecret": "your_client_secret"
}
```

**3. Scrape any URL without credentials (embed mode)**

```json
{
  "startUrls": [
    "https://open.spotify.com/track/0VjIjW4GlUZAMYd2vXMi3b",
    "https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M"
  ]
}
```

**4. An artist's full discography**

```json
{
  "searchQuery": "daft punk",
  "entityTypes": ["artist"],
  "expandArtistAlbums": true,
  "clientId": "your_client_id",
  "clientSecret": "your_client_secret"
}
```

**5. Artist stats — monthly listeners, world rank, play counts (no credentials)**

```json
{
  "startUrls": ["https://open.spotify.com/artist/3TVXtAsR1Inumwj472S9r4"],
  "includeArtistStats": true
}
```

***

### Pricing

**$1.49 per 1,000 items** — you only pay for items actually returned. Failed retries and filtered-out items are never charged.

| Items | Cost |
|---|---|
| 100 | ~$0.15 |
| 1,000 | ~$1.49 |
| 10,000 | ~$14.90 |
| 100,000 | ~$149.00 |

Subscribers pay less at every tier, down to **$0.89 per 1,000** on the Diamond plan.

Use the **Max results** cap to control your spend exactly.

***

### Notes and limitations

- **Keyword search requires API credentials.** Spotify has no public search endpoint without authentication. Credentials are free.
- **Spotify is streaming-only** — there are no purchase prices to scrape. The scraper returns popularity, availability and rich metadata instead.
- **Audio previews** are 30-second clips and are not available for every track.
- **Embed mode** resolves known URLs/URIs only; it returns a core metadata subset (name, artists, duration, explicit, release date, cover, preview, and tracklists for albums/playlists/artist top tracks).
- Respect Spotify's Developer Terms when using their API. This scraper extracts catalogue metadata only — no user data, no audio.

***

### Technical details

- **Auth:** client-credentials OAuth (read-only catalogue) when credentials are supplied; token-free embed extraction otherwise.
- **Memory:** 512 MB.
- **Retry:** automatic retry with exponential backoff, honors Spotify `Retry-After` on rate limits.
- **Output:** every run writes an `OUTPUT` summary and a `HEALTH` status to the key-value store.

***

### Run it on a schedule

This actor is built for repeat use. Set it to run daily, weekly, or hourly, and the data keeps flowing without you touching it.

- **Schedule runs** — open the actor, go to Schedules, and pick a cadence. Each run only charges you for the results it returns.
- **Connect it to your stack** — push results straight to Google Sheets, Slack, a webhook, or your database using Apify Integrations. No glue code needed.
- **Pull results via API** — every run writes a clean dataset you can fetch with one API call, ready for whatever you build on top of it.

Set it once and it runs on its own.

***

### Need a custom scraper?

**[Unfenced Group](https://www.unfencedgroup.nl)** builds Apify actors for any website — for free.

If the site you need isn't in our portfolio yet, just ask. We scope, build, and publish it at no cost to you. You only pay for results — we absorb the compute and proxy costs ourselves. Same pay-per-result pricing, same quality, same standards as every actor in this portfolio.

**Get in touch:** [www.unfencedgroup.nl](https://www.unfencedgroup.nl)

# Actor input Schema

## `searchQuery` (type: `string`):

Keyword(s) to search Spotify (e.g. "the weeknd", "blinding lights"). Requires API credentials below. Leave empty to scrape specific URLs/IDs.

## `entityTypes` (type: `array`):

Which catalogue types to return when searching by keyword (API mode).

## `startUrls` (type: `array`):

Spotify URLs or URIs to scrape directly — albums, tracks, artists or playlists. Works in both modes. Example: https://open.spotify.com/album/4yP0hdKOZPNshxUOjY0cZj or spotify:track:0VjIjW4GlUZAMYd2vXMi3b

## `spotifyIds` (type: `array`):

Spotify IDs or URIs to scrape directly. URIs (spotify:album:ID) are preferred over bare IDs because bare IDs don't carry the entity type.

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

Maximum number of items to return.

## `market` (type: `string`):

ISO country market for availability, playability and market-specific catalogue (API mode).

## `includeTracklist` (type: `boolean`):

Fetch full tracklists for albums and playlists (API mode). Each track includes title, artists, duration, explicit flag and preview. Adds requests per album/playlist.

## `expandArtistAlbums` (type: `boolean`):

When an artist is found, also scrape that artist's albums and singles (API mode).

## `includeArtistStats` (type: `boolean`):

For artists, fetch monthly listeners, follower count, world rank, top listener cities, top tracks with exact play counts, biography, verified status and related artists. Works in both modes — no credentials needed. Pulled from Spotify's internal data, the same numbers the Spotify app shows.

## `filterTypes` (type: `array`):

Post-filter: keep only items of these types.

## `explicitFilter` (type: `string`):

Restrict to clean or explicit items only.

## `genres` (type: `array`):

Filter by genre (substring match, case-insensitive — e.g. "pop", "hip hop"). Genres are available on albums and artists in API mode.

## `minPopularity` (type: `integer`):

Only items with Spotify popularity (0-100) at least this value (API mode).

## `releasedAfter` (type: `string`):

Only items released on or after this date (YYYY-MM-DD).

## `releasedBefore` (type: `string`):

Only items released on or before this date (YYYY-MM-DD).

## `includeMedia` (type: `boolean`):

Include cover art images and audio preview URLs.

## `clientId` (type: `string`):

Your Spotify app Client ID. Get one free at developer.spotify.com/dashboard. Required for keyword search and full metadata (popularity, genres, markets, ISRC/UPC, followers). Without it the actor runs in embed mode (URLs/IDs only).

## `clientSecret` (type: `string`):

Your Spotify app Client Secret. Stored encrypted. Used only for the client-credentials token request.

## `useProxy` (type: `boolean`):

Route requests through Apify Proxy. Off by default.

## Actor input object example

```json
{
  "searchQuery": "",
  "entityTypes": [
    "album",
    "track"
  ],
  "startUrls": [],
  "spotifyIds": [],
  "maxResults": 10,
  "market": "US",
  "includeTracklist": false,
  "expandArtistAlbums": false,
  "includeArtistStats": false,
  "filterTypes": [],
  "explicitFilter": "all",
  "genres": [],
  "releasedAfter": "",
  "releasedBefore": "",
  "includeMedia": true,
  "clientId": "",
  "useProxy": false
}
```

# Actor output Schema

## `results` (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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("unfenced-group/spotify-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 = {}

# Run the Actor and wait for it to finish
run = client.actor("unfenced-group/spotify-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 '{}' |
apify call unfenced-group/spotify-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Spotify Scraper",
        "description": "Scrape Spotify albums, tracks, artists and playlists with full metadata: popularity, genres, available markets, ISRC/UPC, followers, tracklists, cover art and audio previews. Works out of the box; add free Spotify API credentials for keyword search and complete metadata.",
        "version": "0.0",
        "x-build-id": "RqtyMa4AL1tVnmPD9"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/unfenced-group~spotify-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-unfenced-group-spotify-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/unfenced-group~spotify-scraper/runs": {
            "post": {
                "operationId": "runs-sync-unfenced-group-spotify-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/unfenced-group~spotify-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-unfenced-group-spotify-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": {
                    "searchQuery": {
                        "title": "Search query",
                        "type": "string",
                        "description": "Keyword(s) to search Spotify (e.g. \"the weeknd\", \"blinding lights\"). Requires API credentials below. Leave empty to scrape specific URLs/IDs.",
                        "default": ""
                    },
                    "entityTypes": {
                        "title": "What to search for",
                        "type": "array",
                        "description": "Which catalogue types to return when searching by keyword (API mode).",
                        "items": {
                            "type": "string",
                            "enum": [
                                "album",
                                "track",
                                "artist",
                                "playlist"
                            ],
                            "enumTitles": [
                                "Albums",
                                "Tracks",
                                "Artists",
                                "Playlists"
                            ]
                        },
                        "default": [
                            "album",
                            "track"
                        ]
                    },
                    "startUrls": {
                        "title": "Spotify URLs",
                        "type": "array",
                        "description": "Spotify URLs or URIs to scrape directly — albums, tracks, artists or playlists. Works in both modes. Example: https://open.spotify.com/album/4yP0hdKOZPNshxUOjY0cZj or spotify:track:0VjIjW4GlUZAMYd2vXMi3b",
                        "default": [],
                        "items": {
                            "type": "string"
                        }
                    },
                    "spotifyIds": {
                        "title": "Spotify IDs / URIs",
                        "type": "array",
                        "description": "Spotify IDs or URIs to scrape directly. URIs (spotify:album:ID) are preferred over bare IDs because bare IDs don't carry the entity type.",
                        "default": [],
                        "items": {
                            "type": "string"
                        }
                    },
                    "maxResults": {
                        "title": "Max results",
                        "minimum": 1,
                        "type": "integer",
                        "description": "Maximum number of items to return.",
                        "default": 10
                    },
                    "market": {
                        "title": "Market",
                        "enum": [
                            "US",
                            "GB",
                            "DE",
                            "FR",
                            "NL",
                            "ES",
                            "IT",
                            "SE",
                            "BR",
                            "MX",
                            "CA",
                            "AU",
                            "JP",
                            "IN",
                            "KR",
                            "ID",
                            "PH",
                            "AR",
                            "PL",
                            "TR",
                            "ZA",
                            "NG",
                            "AE"
                        ],
                        "type": "string",
                        "description": "ISO country market for availability, playability and market-specific catalogue (API mode).",
                        "default": "US"
                    },
                    "includeTracklist": {
                        "title": "Include tracklists",
                        "type": "boolean",
                        "description": "Fetch full tracklists for albums and playlists (API mode). Each track includes title, artists, duration, explicit flag and preview. Adds requests per album/playlist.",
                        "default": false
                    },
                    "expandArtistAlbums": {
                        "title": "Expand artists to albums",
                        "type": "boolean",
                        "description": "When an artist is found, also scrape that artist's albums and singles (API mode).",
                        "default": false
                    },
                    "includeArtistStats": {
                        "title": "Include artist stats (monthly listeners, world rank)",
                        "type": "boolean",
                        "description": "For artists, fetch monthly listeners, follower count, world rank, top listener cities, top tracks with exact play counts, biography, verified status and related artists. Works in both modes — no credentials needed. Pulled from Spotify's internal data, the same numbers the Spotify app shows.",
                        "default": false
                    },
                    "filterTypes": {
                        "title": "Keep only these types",
                        "type": "array",
                        "description": "Post-filter: keep only items of these types.",
                        "items": {
                            "type": "string",
                            "enum": [
                                "album",
                                "track",
                                "artist",
                                "playlist"
                            ],
                            "enumTitles": [
                                "Albums",
                                "Tracks",
                                "Artists",
                                "Playlists"
                            ]
                        },
                        "default": []
                    },
                    "explicitFilter": {
                        "title": "Explicit content",
                        "enum": [
                            "all",
                            "clean",
                            "explicit"
                        ],
                        "type": "string",
                        "description": "Restrict to clean or explicit items only.",
                        "default": "all"
                    },
                    "genres": {
                        "title": "Genres",
                        "type": "array",
                        "description": "Filter by genre (substring match, case-insensitive — e.g. \"pop\", \"hip hop\"). Genres are available on albums and artists in API mode.",
                        "default": [],
                        "items": {
                            "type": "string"
                        }
                    },
                    "minPopularity": {
                        "title": "Minimum popularity",
                        "type": "integer",
                        "description": "Only items with Spotify popularity (0-100) at least this value (API mode)."
                    },
                    "releasedAfter": {
                        "title": "Released after",
                        "type": "string",
                        "description": "Only items released on or after this date (YYYY-MM-DD).",
                        "default": ""
                    },
                    "releasedBefore": {
                        "title": "Released before",
                        "type": "string",
                        "description": "Only items released on or before this date (YYYY-MM-DD).",
                        "default": ""
                    },
                    "includeMedia": {
                        "title": "Include media",
                        "type": "boolean",
                        "description": "Include cover art images and audio preview URLs.",
                        "default": true
                    },
                    "clientId": {
                        "title": "Spotify Client ID",
                        "type": "string",
                        "description": "Your Spotify app Client ID. Get one free at developer.spotify.com/dashboard. Required for keyword search and full metadata (popularity, genres, markets, ISRC/UPC, followers). Without it the actor runs in embed mode (URLs/IDs only).",
                        "default": ""
                    },
                    "clientSecret": {
                        "title": "Spotify Client Secret",
                        "type": "string",
                        "description": "Your Spotify app Client Secret. Stored encrypted. Used only for the client-credentials token request."
                    },
                    "useProxy": {
                        "title": "Use proxy",
                        "type": "boolean",
                        "description": "Route requests through Apify Proxy. Off by default.",
                        "default": false
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```
