# Spotify Play Count Scraper (`fetch_cat/spotify-play-count-scraper`) Actor

Export timestamped public Spotify track play counts and artist listener metrics from watchlist URLs.

- **URL**: https://apify.com/fetch\_cat/spotify-play-count-scraper.md
- **Developed by:** [Hanna Nosova](https://apify.com/fetch_cat) (community)
- **Categories:** Social media
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.60 / 1,000 item processeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

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 Play Count Scraper

Export timestamped public Spotify track play counts, artist monthly listeners, and album metadata from Spotify watchlist URLs.

### Monitor Spotify music metrics over time

Spotify Play Count Scraper is built for music marketers, labels, playlist analysts, and creator-economy teams that need a repeatable public-metric export.

Use it to:

- Track public play counts for a watchlist of Spotify tracks.
- Record public monthly-listener values for artists.
- Save timestamps so exports can be compared across reporting periods.
- Keep album identity and release metadata alongside a metric watchlist.

It works with public Spotify URLs. It does not access Spotify for Artists, listener accounts, user libraries, or private analytics.

### Who is it for?

**Music marketers** can compare track momentum between campaign snapshots.

**Record labels and managers** can maintain an exportable artist and release watchlist.

**Playlist analysts** can collect public track identifiers and visible performance metrics for reporting workflows.

**Creator-economy researchers** can build timestamped datasets for public music-performance analysis.

### Ready-to-run examples

Open a public example to inspect its input, run it, or reuse it as a task:

- [Export Spotify album track performance](https://apify.com/fetch_cat/spotify-play-count-scraper/examples/spotify-album-track-performance-sample)
- [Monitor Spotify artist monthly listeners](https://apify.com/fetch_cat/spotify-play-count-scraper/examples/spotify-artist-monthly-listeners-monitor)
- [Monitor Spotify track play counts](https://apify.com/fetch_cat/spotify-play-count-scraper/examples/spotify-track-play-count-monitor)

#### Start with a track watchlist

Paste public Spotify URLs and use a low `maxItems` value for a quick first export.

```json
{
  "trackUrls": [
    "https://open.spotify.com/track/3n3Ppam7vgaVa1iaRUc9Lp"
  ],
  "artistUrls": [
    "https://open.spotify.com/artist/0C0XlULifJtAgn6ZNCW2eu"
  ],
  "maxItems": 10,
  "includeRelatedTracks": false
}
```

### Spotify monthly listeners scraper and artist metrics scraper

#### Track play-count monitoring

Add one or more `trackUrls`. Keep `maxItems` close to the number of watchlist URLs when you only need requested tracks.

```json
{
  "trackUrls": [
    "https://open.spotify.com/track/3n3Ppam7vgaVa1iaRUc9Lp"
  ],
  "maxItems": 1
}
```

#### Artist monthly-listener monitoring

Add public artist URLs to return a timestamped monthly-listener metric when Spotify exposes one.

```json
{
  "artistUrls": [
    "https://open.spotify.com/artist/0C0XlULifJtAgn6ZNCW2eu"
  ],
  "maxItems": 1,
  "failOnUnavailableMetric": false
}
```

#### Artist page with related tracks

Set `includeRelatedTracks` when you also want public track rows shown on a requested artist or album page.

```json
{
  "artistUrls": [
    "https://open.spotify.com/artist/0C0XlULifJtAgn6ZNCW2eu"
  ],
  "includeRelatedTracks": true,
  "maxItems": 10
}
```

### Example output

```json
{
  "entityType": "track",
  "spotifyId": "3n3Ppam7vgaVa1iaRUc9Lp",
  "url": "https://open.spotify.com/track/3n3Ppam7vgaVa1iaRUc9Lp",
  "name": "Mr. Brightside",
  "artistNames": ["The Killers"],
  "albumName": "Hot Fuss",
  "playCount": 3427230508,
  "monthlyListeners": null,
  "releaseDate": "2004-06-15T00:00:00Z",
  "snapshotAt": "2026-08-26T00:00:00.000Z",
  "scrapedAt": "2026-08-26T00:00:00.000Z",
  "metricAvailability": "available",
  "sourceInput": "https://open.spotify.com/track/3n3Ppam7vgaVa1iaRUc9Lp",
  "isTarget": true
}
```

### Input settings

| Input | Description |
| --- | --- |
| `trackUrls` | Public Spotify track URLs. Returns an exact public play count when Spotify exposes it. |
| `artistUrls` | Public Spotify artist URLs. Returns public monthly listeners when exposed. |
| `albumUrls` | Public Spotify album URLs. Returns album metadata; Spotify does not provide one aggregate album play count. |
| `maxItems` | Maximum rows to persist (1–1000; default 10). |
| `includeRelatedTracks` | Add public track rows exposed on requested artist or album pages. |
| `failOnUnavailableMetric` | Skip a target rather than save its unavailable metric row; remaining targets continue. |

### Output fields

| Field | Description |
| --- | --- |
| `entityType`, `spotifyId`, `url`, `name` | Spotify entity identity and canonical URL. |
| `artistNames`, `albumName`, `releaseDate` | Public track, artist, or album metadata when applicable. |
| `playCount` | Public exact track play count; `null` when Spotify does not expose an applicable value. |
| `monthlyListeners` | Public artist monthly-listener metric; `null` for non-artist rows. |
| `snapshotAt`, `scrapedAt` | ISO timestamps for the metric capture. |
| `metricAvailability`, `warnings` | Explicit availability state and any source limitation. |
| `sourceInput`, `isTarget` | Requested input provenance and target-versus-related-track indicator. |

### Pricing and limits

This Actor charges once when a run starts and for each dataset row it successfully saves. Check the live [Pricing tab](https://apify.com/fetch_cat/spotify-play-count-scraper/pricing) for current rates.

`maxItems` is limited to 1,000 rows per run. A row is charged only after it is saved to the dataset.

### Tips and limits

- Use track URLs when exact track play counts are required.
- Keep `snapshotAt` when comparing a metric across reporting periods.
- Invalid Spotify URLs are ignored. If no valid URL remains, the run fails before browsing.
- A public metric can change between runs.
- Public pages may omit a metric. This Actor never substitutes a zero for an unavailable metric.
- Album rows describe the album; Spotify does not expose one aggregate public album play count.

### API Usage: Spotify play count API

Use the Apify API to run a saved or scheduled metric watchlist.

#### Node.js

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('fetch_cat/spotify-play-count-scraper').call({
    trackUrls: ['https://open.spotify.com/track/3n3Ppam7vgaVa1iaRUc9Lp'],
    maxItems: 1,
});
console.log(run.defaultDatasetId);
```

#### Python

```python
from apify_client import ApifyClient
import os

client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('fetch_cat/spotify-play-count-scraper').call(run_input={
    'trackUrls': ['https://open.spotify.com/track/3n3Ppam7vgaVa1iaRUc9Lp'],
    'maxItems': 1,
})
print(run['defaultDatasetId'])
```

#### cURL

```bash
curl -X POST "https://api.apify.com/v2/acts/fetch_cat~spotify-play-count-scraper/runs" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"trackUrls":["https://open.spotify.com/track/3n3Ppam7vgaVa1iaRUc9Lp"],"maxItems":1}'
```

### MCP and agents

Connect an MCP-capable assistant to this Actor with:

```bash
claude mcp add --transport http apify "https://mcp.apify.com?tools=fetch_cat/spotify-play-count-scraper"
```

Or add this server configuration to an MCP client:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=fetch_cat/spotify-play-count-scraper"
    }
  }
}
```

#### Example prompts

- “Run my Spotify track watchlist and return each play count with `snapshotAt`.”
- “Compare this artist's monthly-listener snapshots from two datasets.”
- “Export public metadata and exact counts for these Spotify track URLs.”

### FAQ

**What data can I export with spotify play count scraper?** Public track play counts, artist monthly listeners when exposed, album metadata, canonical Spotify IDs, and timestamped availability states.

**Can I run Spotify Play Count Scraper through an API, schedule, or MCP client?** Yes. Use the Spotify play count API examples above, schedule a saved watchlist input in Apify, or connect through the MCP configuration in this README.

**How much does it cost to use Spotify Play Count Scraper?** It charges once when the run starts and once per saved dataset row. See the live Pricing tab for current rates.

**Can it access Spotify for Artists or private listener data?** No. It only returns public page data and does not accept Spotify credentials.

**Why is `playCount` null for an album?** Spotify exposes per-track counts, not one aggregate album count.

**What happens when a public metric is unavailable?** The row states its availability unless `failOnUnavailableMetric` tells the Actor to skip it; other valid targets continue.

### Related Actors

- [Spotify Scraper](https://apify.com/fetch_cat/spotify-scraper) — export broader public Spotify entity metadata when you need more than monitoring metrics.
- [SoundCloud Tracks Search Scraper](https://apify.com/fetch_cat/soundcloud-tracks-search-scraper) — search public SoundCloud tracks for cross-platform music research.
- [YouTube Video Details Scraper](https://apify.com/fetch_cat/youtube-video-details-scraper) — export public YouTube video metadata for video-performance workflows.
- [YouTube Channel Details Scraper](https://apify.com/fetch_cat/youtube-channel-details-scraper) — collect public channel metadata for creator monitoring.
- [YouTube Playlist Videos Scraper](https://apify.com/fetch_cat/youtube-playlist-videos-scraper) — export public playlist video metadata.

### Support

Open an issue from the Actor page with the public Spotify URL, run ID, and expected public field. Do not share credentials or private account information.

# Actor input Schema

## `trackUrls` (type: `array`):

Public Spotify track URLs. Exact public play counts are returned when Spotify exposes them.

## `artistUrls` (type: `array`):

Public Spotify artist URLs to monitor.

## `albumUrls` (type: `array`):

Public Spotify album URLs to monitor.

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

Maximum number of valid watchlist URLs to process.

## `includeRelatedTracks` (type: `boolean`):

For artist or album URLs, include public related track rows that Spotify exposes on the requested page.

## `failOnUnavailableMetric` (type: `boolean`):

Skip a target instead of preserving an unavailable metric row; remaining watchlist targets continue.

## Actor input object example

```json
{
  "trackUrls": [
    {
      "url": "https://open.spotify.com/track/3n3Ppam7vgaVa1iaRUc9Lp"
    }
  ],
  "artistUrls": [],
  "albumUrls": [],
  "maxItems": 10,
  "includeRelatedTracks": false,
  "failOnUnavailableMetric": false
}
```

# Actor output Schema

## `overview` (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 = {
    "trackUrls": [
        {
            "url": "https://open.spotify.com/track/3n3Ppam7vgaVa1iaRUc9Lp"
        }
    ],
    "artistUrls": [],
    "albumUrls": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("fetch_cat/spotify-play-count-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 = {
    "trackUrls": [{ "url": "https://open.spotify.com/track/3n3Ppam7vgaVa1iaRUc9Lp" }],
    "artistUrls": [],
    "albumUrls": [],
}

# Run the Actor and wait for it to finish
run = client.actor("fetch_cat/spotify-play-count-scraper").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "trackUrls": [
    {
      "url": "https://open.spotify.com/track/3n3Ppam7vgaVa1iaRUc9Lp"
    }
  ],
  "artistUrls": [],
  "albumUrls": []
}' |
apify call fetch_cat/spotify-play-count-scraper --silent --output-dataset

```

## MCP server setup

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

```

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

## OpenAPI specification

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