# 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 web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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

Use this Apify Actor to get Spotify artist monthly listeners, followers, world rank, and top listener cities from an artist URL, artist ID, Spotify URI, or artist name. It accepts a list of artist inputs, returns one dataset record per successfully scraped artist, and produces structured fields that are useful for analytics, routing, and agent workflows. The output includes artist identity fields plus popularity metrics and city data, so each record can be used as a compact snapshot of one artist at run time.

### Best fit and connected workflows

This Actor fits workflows that start with an artist name or link and need Spotify artist popularity data in a structured format. It is useful for:

- roster monitoring and artist benchmarking
- audience geography review using top listener cities
- enrichment steps in music marketing or A\&R pipelines
- AI agent tasks that need a single tool to resolve an artist and return current Spotify metrics

Because it is an Apify Actor, it can be used through Apify MCP as part of a larger agent flow, while still keeping the task focused on artist-level Spotify data.

### Practical scenario

A music marketer is preparing a campaign for a shortlist of artists. They start with a list that includes a plain artist name and a Spotify artist URL. The Actor returns each artist's name, monthly listeners, followers, world rank, and top listener cities. The marketer uses the city list to decide where to concentrate ad spend and uses the world rank and listener counts to compare relative scale across the shortlist. The next action is to export the dataset items into a spreadsheet or pass them into a downstream reporting workflow.

### Input

The Actor accepts these input fields:

| Field | Type | Purpose |
|---|---|---|
| `artists` | array of strings | One entry per artist. Accepts a Spotify artist URL, Spotify URI, bare 22-character artist ID, or plain artist name. |
| `topCitiesLimit` | integer | Number of top listener cities to include per artist. Range: 0 to 50. Spotify exposes up to 5 cities publicly. |
| `maxResults` | integer | Hard cap on the number of artists processed and billed in one run. |
| `proxyConfiguration` | object | Proxy used for Spotify requests. Apify Proxy is enabled by default. |

#### Focused JSON input example

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

### Output

Each dataset item represents one artist that was successfully scraped.

| Field | Type | Meaning |
|---|---|---|
| `query` | string or null | Original input value for the artist. |
| `resolvedVia` | string or null | How the input was resolved, such as URL, URI, ID, or search. |
| `type` | string | Record type returned by Spotify. |
| `id` | string or null | Spotify artist ID. |
| `uri` | string or null | Spotify artist URI. |
| `url` | string or null | Spotify artist URL. |
| `name` | string or null | Artist name returned by Spotify. |
| `verified` | boolean or null | Verified status when available. |
| `monthlyListeners` | integer or null | Monthly listeners value. |
| `followers` | integer or null | Spotify follower count. |
| `worldRank` | integer or null | World rank value when Spotify exposes it. |
| `topCities` | array or null | Top listener cities, ordered by listener count. |
| `avatarImage` | string or null | Artist image URL. |
| `scrapedAt` | string or null | Timestamp for when the record was scraped. |

#### Illustrative output record

```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
    }
  ],
  "avatarImage": "https://i.scdn.co/image/...",
  "scrapedAt": "2026-06-20T22:41:09.412Z"
}
```

### How it works

The Actor resolves each artist input to a Spotify artist and then queries Spotify's Partner API `queryArtistOverview` operation. According to the live contract, it is HTTP-only and uses a self-healing TOTP token plus operation hash extracted live from Spotify's web player. The actor does not launch a browser. Names are resolved to the top matching artist, while URLs, URIs, and bare IDs are used directly.

### Pricing

Spotify Monthly Listeners Scraper uses Pay per event plus Apify platform usage. The charged events are:

- Actor start
- Artist scraped

An artist is billed when it is successfully returned with monthly listeners, followers, world rank, and top cities. Skipped inputs and non-artist links are not billed. Apify platform usage is billed separately according to your Apify plan and resource consumption. For the current pricing details, open the live Pricing tab in the Apify Console.

For a simple example, a run that scrapes twenty artists triggers twenty artist events plus one Actor start event.

### Use with AI agents (MCP)

This Actor is available as an Apify Actor usable through Apify MCP. It is designed for agent workflows that need a compact tool call to resolve Spotify artist inputs and retrieve structured artist-level metadata.

**Actor identity:** `khadinakbar/spotify-monthly-listeners-scraper`

Tool description: accept a list of Spotify artist URLs, URIs, IDs, or names and return one record per successfully scraped artist with monthly listeners, followers, world rank, top listener cities, and identity fields.

> Get the Spotify artist profile for this artist name and return monthly listeners, followers, world rank, top listener cities, and the resolved Spotify URL. Use the artist's own Spotify page when possible.

Output interpretation:

- `resolvedVia` shows how the artist was matched.
- `query` preserves the original input.
- `monthlyListeners`, `followers`, and `worldRank` are the main popularity fields.
- `topCities` provides the publicly exposed top listener cities, ordered by listener count.
- `scrapedAt` marks when the record was collected.

Provenance and scope:

- Data comes from Spotify artist data exposed through the actor's HTTP-based scraping flow.
- The scope is artist-level Spotify popularity data only.

Pagination and cost guidance:

- Feed multiple artists in one input array.
- Use `maxResults` to cap the number of processed and billed artists.
- Use `topCitiesLimit` to control how many city rows are included per artist.
- Billing follows the actor's Pay per event contract.

### Apify API example

#### JavaScript

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

const client = new ApifyClient({
  token: process.env.APIFY_TOKEN,
});

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

const { items } = await client.dataset(run.defaultDatasetId).listItems();

for (const item of items) {
  console.log(`${item.name}: ${item.monthlyListeners} monthly listeners`);
}
```

### Best results and outcome guidance

Use exact Spotify artist URLs or artist IDs when you want the most direct match. Use a plain artist name when you want the Actor to resolve the top matching artist on Spotify. Set `topCitiesLimit` to 0 when you only need core popularity fields and want smaller records. Keep `maxResults` aligned with the number of artists you intend to process in one run.

### Focused standalone workflow

Spotify Monthly Listeners Scraper is designed as a focused standalone workflow for the public input and structured output contract described above.

### Design note

I found that the live dataset contract exposes a single flat record per artist, with `query`, `resolvedVia`, `monthlyListeners`, `followers`, `worldRank`, `topCities`, and `scrapedAt` among the fields, which makes the Actor straightforward to consume in downstream workflows.

### FAQ

**Can I paste a Spotify artist URL, URI, or ID?**\
Yes. The Actor accepts all three, along with a plain artist name.

**What happens with a Spotify album or playlist link?**\
The input schema is for artist entries. Artist URLs, URIs, IDs, and names are the intended inputs.

**How many top listener cities can I request?**\
The `topCitiesLimit` field accepts 0 to 50, while Spotify exposes up to 5 cities publicly.

**What does `resolvedVia` tell me?**\
It shows whether the artist was resolved from a URL, URI, ID, or search input.

**Is this Actor usable through Apify MCP?**\
Yes. It is an Apify Actor that is MCP-ready and designed for agent workflows.

**Can I use this for multiple artists in one run?**\
Yes. Pass an array of artist inputs and control the run with `maxResults`.

### Responsible use

Use the data in ways that respect Spotify's terms, applicable laws, and your own data-handling requirements. This Actor collects publicly exposed Spotify artist information and returns it in structured form for legitimate research, operations, automation, and agent workflows.

# 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

## `output` (type: `string`):

Normalized terminal outcome for agent and API clients.

## `runSummary` (type: `string`):

Detailed terminal outcome, counts, and charge events.

# 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

Download the OpenAPI definition: https://api.apify.com/v2/actors/IroXl49HgeM3jpSmv/builds/lTIwj8m0JlE3KRcaX/openapi.json