# Spotify Monthly Listeners Scraper (`khadinakbar/spotify-monthly-listeners-scraper`) Actor

Get Spotify artist monthly listeners, followers, world rank, and top listener cities from an artist URL, ID, or name. HTTP-only, no API key, MCP-ready.

- **URL**: https://apify.com/khadinakbar/spotify-monthly-listeners-scraper.md
- **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community)
- **Categories:** Social media, MCP servers, AI
- **Stats:** 1 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 artist scrapeds

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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 Monthly Listeners Scraper

Get any Spotify artist's **monthly listeners, followers, world rank, and top listener cities** — from an artist URL, ID, or just a name. No API key, no login, no Spotify app registration. Built for music marketers, A&R, playlist pluggers, distributors, and AI agents.

### What it does

Give it a list of artists. For each one it returns the live popularity numbers Spotify shows on the artist page, as clean structured JSON:

- **Monthly listeners** — the headline artist KPI.
- **Followers** — total Spotify followers.
- **World rank** — global popularity position (when Spotify exposes it).
- **Top listener cities** — up to 5 cities with per-city listener counts (city, country, region).
- Artist identity — name, verified status, Spotify URL/URI, ID, avatar image.

You can mix input styles freely in one run:

| You paste | It does |
|---|---|
| `Taylor Swift` (a name) | Searches Spotify, takes the top matching artist |
| `https://open.spotify.com/artist/06HL4z0CvFAxyc27GXpf02` | Uses that exact artist |
| `spotify:artist:06HL4z0CvFAxyc27GXpf02` | Uses that exact artist |
| `06HL4z0CvFAxyc27GXpf02` (bare 22-char ID) | Treats it as an artist ID |

Album, track, and playlist links are **not** artists — they are skipped with a clear hint so you don't get charged for the wrong thing.

### When to use it

- Track artist momentum week over week for marketing or A&R.
- Benchmark a roster or a competitor set by monthly listeners.
- Find where an artist's audience actually lives (top cities) for tour routing or ad targeting.
- Feed an AI agent a name and get back structured popularity data in one tool call.

**When not to use it:** if you need albums, tracks, playlists, podcasts, play counts, or full discography, use the broader **[Spotify All-in-One Scraper](https://apify.com/khadinakbar/spotify-all-in-one-scraper)**. This actor is deliberately lean and focused on listener/popularity stats only.

### Output

One flat record per artist:

```json
{
  "query": "Taylor Swift",
  "resolvedVia": "search",
  "type": "artist",
  "id": "06HL4z0CvFAxyc27GXpf02",
  "uri": "spotify:artist:06HL4z0CvFAxyc27GXpf02",
  "url": "https://open.spotify.com/artist/06HL4z0CvFAxyc27GXpf02",
  "name": "Taylor Swift",
  "verified": true,
  "monthlyListeners": 84213765,
  "followers": 132847901,
  "worldRank": 3,
  "topCities": [
    { "city": "London", "country": "GB", "region": "England", "listeners": 1284551 },
    { "city": "New York", "country": "US", "region": "New York", "listeners": 1102934 }
  ],
  "avatarImage": "https://i.scdn.co/image/...",
  "scrapedAt": "2026-06-20T22:41:09.412Z"
}
````

`resolvedVia` tells you how the input was matched: `url`, `uri`, `id`, or `search`. When matched by name, double-check `name` against what you intended — search returns the single most popular match.

### Pricing

Pay-per-event, premium tier:

| Event | Price |
|---|---|
| Actor start | $0.00005 |
| Artist scraped | $0.005 per artist |

You are billed **only** for artists that successfully return data. Skipped inputs (non-artist links, blank lines) and failed lookups are **not** charged. A 100-artist run costs about **$0.50**. The run prints its maximum cost cap up front and the actual billed amount at the end.

### Input

| Field | Type | Default | Notes |
|---|---|---|---|
| `artists` | string\[] | — | Artist URLs, URIs, IDs, or names. Mix freely. |
| `topCitiesLimit` | integer | `5` | Top cities per artist (0–50). Set 0 to omit. Does not affect billing. |
| `maxResults` | integer | `50` | Hard cap on artists processed and billed. |
| `proxyConfiguration` | object | Apify Proxy (auto) | Datacenter US by default; works for Spotify. |

#### Example input

```json
{
  "artists": [
    "Taylor Swift",
    "https://open.spotify.com/artist/4q3ewBCX7sLwd24euuV69X",
    "Drake",
    "spotify:artist:1Xyo4u8uXC1ZmMpatF05PJ"
  ],
  "topCitiesLimit": 5,
  "maxResults": 50
}
```

### Run it from code

#### Node.js (apify-client)

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'YOUR_APIFY_TOKEN' });

const run = await client.actor('khadinakbar/spotify-monthly-listeners-scraper').call({
    artists: ['Taylor Swift', 'The Weeknd', 'Bad Bunny'],
    topCitiesLimit: 5,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
for (const a of items) {
    console.log(`${a.name}: ${a.monthlyListeners?.toLocaleString()} monthly listeners (#${a.worldRank})`);
}
```

#### Python (apify-client)

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")

run = client.actor("khadinakbar/spotify-monthly-listeners-scraper").call(run_input={
    "artists": ["Taylor Swift", "The Weeknd", "Bad Bunny"],
    "topCitiesLimit": 5,
})

for a in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(a["name"], a["monthlyListeners"], a.get("worldRank"))
```

### Use with AI agents (MCP)

This actor is MCP-ready. Connect via Apify's hosted MCP server and an agent can call it with a single artist name or URL and receive structured popularity data. Input is narrow (one `artists` list), output is flat and small (well under the per-item token budget), and errors are actionable.

### How it works

The actor talks to the same endpoints Spotify's own web player uses. It extracts the current rotating auth token from the live web-player bundle (so it self-heals when Spotify rotates the secret), then calls the Partner API's `queryArtistOverview` operation for each artist. No browser is launched — it is pure HTTP, which keeps runs fast and cheap. Names are resolved to artists via Spotify's `searchDesktop` operation.

### Reliability

- **Self-healing auth** — the token secret and operation hash are pulled live from Spotify's web player each run, so routine rotations don't break the actor.
- **Honest failure** — if Spotify blocks every request, the run fails clearly instead of silently returning an empty dataset.
- **Soft input handling** — bad or non-artist inputs are skipped with a reason, never crash the run.
- **Cost guard** — the run respects `maxResults` and never bills past the cap.

### FAQ

**Do I need a Spotify account or API key?** No. Nothing to register, no login.

**How fresh are the numbers?** They are read live at run time — the same values shown on the public artist page.

**Why was an album/playlist link skipped?** Monthly listeners is an artist-level metric. Paste the artist's own page, ID, or name instead.

**Can it return more than 5 cities?** Spotify only exposes the top 5 listener cities publicly, so that is the ceiling.

**A name matched the wrong artist — why?** Name search returns the single most popular match. For exact control, paste the artist's Spotify URL or ID.

**Does it work outside the US?** The data is global. The default proxy is US datacenter; you can switch proxy region in the input.

### Legal & compliance

This actor collects only publicly available data shown on Spotify's public artist pages. It does not log in, bypass authentication, or access private/account data. You are responsible for using the data in compliance with Spotify's Terms of Service, applicable laws, and any data-protection regulations (e.g. GDPR) that apply to your use case. Not affiliated with or endorsed by Spotify.

### Related actors

- [Spotify All-in-One Scraper](https://apify.com/khadinakbar/spotify-all-in-one-scraper) — artists, albums, tracks, playlists, podcasts, episodes, search, play counts.

# Actor input Schema

## `artists` (type: `array`):

One entry per artist. Accepts a Spotify artist URL (https://open.spotify.com/artist/06HL4z0CvFAxyc27GXpf02), a URI (spotify:artist:06HL4z0CvFAxyc27GXpf02), a bare 22-character artist ID, or a plain artist name (e.g. 'Taylor Swift') which is resolved to the top matching artist. Album/track/playlist links are not artists and are skipped with a hint — use the artist's own page.

## `topCitiesLimit` (type: `integer`):

How many top listener cities to include per artist, ordered by listener count (Spotify exposes up to 5). Set 0 to omit cities entirely and keep records small. Range 0-50. Defaults to 5. Does not change billing — one charge per artist regardless.

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

Hard cap on the number of artists processed and billed in this run. Each successfully scraped artist counts as one billable result; skipped/failed inputs are not billed. Use it to control cost on large lists. Defaults to 50.

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

Proxy used for all Spotify requests. Apify Proxy (automatic datacenter, US) is enabled by default and works for Spotify's token and Partner API. Switch to Residential only if you have that proxy group and see blocks. Leave as-is otherwise.

## Actor input object example

```json
{
  "artists": [
    "The Weeknd",
    "spotify:artist:1Xyo4u8uXC1ZmMpatF05PJ"
  ],
  "topCitiesLimit": 5,
  "maxResults": 50,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# 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 = {
    "artists": [
        "Taylor Swift",
        "https://open.spotify.com/artist/4q3ewBCX7sLwd24euuV69X",
        "Drake"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("khadinakbar/spotify-monthly-listeners-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 = {
    "artists": [
        "Taylor Swift",
        "https://open.spotify.com/artist/4q3ewBCX7sLwd24euuV69X",
        "Drake",
    ],
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("khadinakbar/spotify-monthly-listeners-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 '{
  "artists": [
    "Taylor Swift",
    "https://open.spotify.com/artist/4q3ewBCX7sLwd24euuV69X",
    "Drake"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call khadinakbar/spotify-monthly-listeners-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Spotify Monthly Listeners Scraper",
        "description": "Get Spotify artist monthly listeners, followers, world rank, and top listener cities from an artist URL, ID, or name. HTTP-only, no API key, MCP-ready.",
        "version": "0.1",
        "x-build-id": "ikOigBQOasUnuRRN1"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/khadinakbar~spotify-monthly-listeners-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-khadinakbar-spotify-monthly-listeners-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/khadinakbar~spotify-monthly-listeners-scraper/runs": {
            "post": {
                "operationId": "runs-sync-khadinakbar-spotify-monthly-listeners-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/khadinakbar~spotify-monthly-listeners-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-khadinakbar-spotify-monthly-listeners-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": {
                    "artists": {
                        "title": "Artists (URLs, IDs, or names)",
                        "type": "array",
                        "description": "One entry per artist. Accepts a Spotify artist URL (https://open.spotify.com/artist/06HL4z0CvFAxyc27GXpf02), a URI (spotify:artist:06HL4z0CvFAxyc27GXpf02), a bare 22-character artist ID, or a plain artist name (e.g. 'Taylor Swift') which is resolved to the top matching artist. Album/track/playlist links are not artists and are skipped with a hint — use the artist's own page.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "topCitiesLimit": {
                        "title": "Top cities per artist",
                        "minimum": 0,
                        "maximum": 50,
                        "type": "integer",
                        "description": "How many top listener cities to include per artist, ordered by listener count (Spotify exposes up to 5). Set 0 to omit cities entirely and keep records small. Range 0-50. Defaults to 5. Does not change billing — one charge per artist regardless.",
                        "default": 5
                    },
                    "maxResults": {
                        "title": "Max results",
                        "minimum": 1,
                        "type": "integer",
                        "description": "Hard cap on the number of artists processed and billed in this run. Each successfully scraped artist counts as one billable result; skipped/failed inputs are not billed. Use it to control cost on large lists. Defaults to 50.",
                        "default": 50
                    },
                    "proxyConfiguration": {
                        "title": "Proxy configuration",
                        "type": "object",
                        "description": "Proxy used for all Spotify requests. Apify Proxy (automatic datacenter, US) is enabled by default and works for Spotify's token and Partner API. Switch to Residential only if you have that proxy group and see blocks. Leave as-is otherwise.",
                        "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```