# Spotify Catalog Intelligence & Monitoring (`fetchfinch/spotify-public-catalog-metadata`) Actor

Collect structured Spotify data for artists, tracks, albums, playlists, and podcasts. Monitor changes, analyze playlist networks, and discover artists for A\&R research.

- **URL**: https://apify.com/fetchfinch/spotify-public-catalog-metadata.md
- **Developed by:** [Fetch Finch](https://apify.com/fetchfinch) (community)
- **Categories:** Social media, Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 dataset items

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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 Catalog Intelligence

Turn public Spotify catalog pages into structured data for music research,
playlist analysis, artist discovery, and automated monitoring.

This Actor supports direct Spotify URLs, Spotify URIs, IDs, and catalog search
queries. Results are written to an Apify Dataset and can be downloaded as JSON,
CSV, or Excel, or consumed through the Apify API and integrations.

### What you can do

- Collect artist profiles, listener and follower metrics, releases, top tracks,
  and related artists.
- Collect track metadata, play counts, artist references, albums, release dates,
  durations, previews, and identifiers.
- Collect album and playlist metadata with their visible track listings.
- Collect podcast show and episode metadata, including descriptions, publishers,
  release dates, durations, and show relationships.
- Monitor catalog entities over time and receive compact change events.
- Analyze playlist composition and export a graph of playlists, tracks, artists,
  and albums.
- Search for artists and rank enriched results for discovery and A\&R research.

### Run modes

#### Snapshot

The default mode returns the current records for your targets and searches.

#### Monitor changes

Set `mode` to `monitor` to compare each successful fetch with its previous
successful snapshot. The first run emits `first_seen` events. Later runs emit
`updated` events with changed field paths, playlist additions/removals/position
changes, and numeric metric deltas where available.

```json
{
  "mode": "monitor",
  "stateStoreName": "my-artist-monitor",
  "historyDatasetName": "my-artist-history",
  "onlyChanges": true,
  "targets": [
    "https://open.spotify.com/artist/0gxyHStUsqpMadRV0Di1Qt"
  ]
}
```

Use `onlyChanges` for compact alert or webhook payloads. Use `changePreset` to
keep all changes, playlist changes, or metric changes. `ignoredFields` and
`metricThresholdPercent` help reduce noisy alerts.

For recurring monitoring, create an Apify Schedule using the same input and keep
the `stateStoreName` and `historyDatasetName` values stable between runs. Attach
an Apify Webhook to send new run or dataset events to your application.

#### Playlist intelligence

Set `mode` to `playlist_intelligence` to return the playlist record, composition
metrics, and a bounded graph of related playlists, tracks, artists, and albums.
Set `maxGraphNodes` to control output size.

```json
{
  "mode": "playlist_intelligence",
  "maxTracks": 100,
  "maxGraphNodes": 500,
  "targets": [
    "https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M"
  ]
}
```

#### Artist discovery

Set `mode` to `discover` to search the artist catalog, enrich the matching
artists, rank them, and optionally filter by listeners, followers, or release
count.

```json
{
  "mode": "discover",
  "searchQueries": ["indie electronic"],
  "searchTypes": ["artist"],
  "enrichSearchResults": true,
  "rankBy": "monthly_listeners",
  "minMonthlyListeners": 10000,
  "maxItems": 25
}
```

### Input

Targets can be Spotify URLs or typed Spotify URIs. A raw 22-character Spotify
ID requires an explicit `targetType` because the ID itself does not identify
whether it belongs to an artist, track, album, playlist, show, or episode.

```json
{
  "targets": [
    "https://open.spotify.com/artist/0gxyHStUsqpMadRV0Di1Qt",
    "spotify:track:4uLU6hMCjMI75M1A2tKUQC"
  ],
  "searchQueries": ["daft punk"],
  "searchTypes": ["artist", "track"],
  "enrichSearchResults": false,
  "maxSearchResults": 20,
  "maxTracks": 100,
  "maxEpisodes": 50,
  "maxItems": 100
}
```

Search results are sparse by default. Set `enrichSearchResults` to fetch full
records for each matching entity. Use `maxItems`, `maxTracks`, and
`maxEpisodes` to keep runs bounded and predictable.

### Output

Every dataset row includes a consistent envelope such as `record_type`, `id`,
`uri`, `url`, `status`, and `scraped_at`, together with the available fields for
that entity.

Depending on the mode, the dataset can also contain:

- `change` rows with `change_type`, `changed_fields`, `playlist_changes`, and
  `metric_deltas`.
- `analysis` rows with playlist composition metrics such as unique artists,
  duplicate tracks, concentration, and diversity.
- `node` and `edge` rows for graph analysis.
- Discovery fields such as `discovery_rank`, `ranked_by`, and release counts.

Successful monitor snapshots and change events are also appended to the named
history Dataset. The latest run summary is available in the run's default
Key-Value Store under the `OUTPUT` key.

### Preconfigured Tasks

The Actor includes ready-to-run examples for catalog lookup, track performance,
artist and album research, podcast lookup, playlist intelligence, graph
analysis, artist discovery, growth monitoring, playlist change monitoring,
low-noise alerts, and historical archiving. Open the Actor's **Tasks** tab to
run one of these workflows or save your own configuration.

### Integrations

Use the standard Apify API, Dataset exports, Schedules, Webhooks, Make, Zapier,
Slack, Google Sheets, or your own application. The Actor is designed so a
single run can be used as a one-time export, a recurring monitor, or an input to
another workflow.

### Data scope

The Actor returns publicly available Spotify catalog metadata. Private account
data, listening history, and private playlists are not included.

### Support

If a run produces unexpected results, include the Apify run ID, sanitized input,
one reproducible public Spotify URL, and the expected versus actual output when
reporting the issue.

# Actor input Schema

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

Snapshot returns current records. Monitor tracks changes. Playlist intelligence adds graph and composition records. Discover runs an artist-focused enriched search.

## `stateStoreName` (type: `string`):

Named Apify Key-Value Store used to keep the previous successful snapshot in monitor mode.

## `historyDatasetName` (type: `string`):

Named Apify Dataset used to append successful snapshots in monitor mode.

## `onlyChanges` (type: `boolean`):

In monitor mode, omit current snapshot records from the default dataset and return only change records.

## `changePreset` (type: `string`):

Choose which monitor events should be emitted after the first snapshot.

## `ignoredFields` (type: `array`):

Optional exact JSON field paths to ignore during monitor comparisons.

## `metricThresholdPercent` (type: `number`):

Ignore monitored numeric metric changes smaller than this percentage.

## `maxGraphNodes` (type: `integer`):

Upper bound for node records emitted by playlist intelligence mode.

## `rankBy` (type: `string`):

Artist field used to rank enriched discovery results.

## `minMonthlyListeners` (type: `integer`):

In discover mode, keep only artists at or above this monthly listener count.

## `maxMonthlyListeners` (type: `integer`):

In discover mode, keep only artists at or below this monthly listener count.

## `minFollowers` (type: `integer`):

In discover mode, keep only artists at or above this follower count.

## `maxFollowers` (type: `integer`):

In discover mode, keep only artists at or below this follower count.

## `minReleases` (type: `integer`):

In discover mode, keep only artists with at least this many releases.

## `targets` (type: `array`):

Spotify URLs or spotify:type:id URIs. Raw 22-character IDs are also accepted when Target type is selected.

## `targetType` (type: `string`):

Use Auto for URLs and URIs. Select an entity type when providing raw Spotify IDs.

## `searchQueries` (type: `array`):

Optional public Spotify catalog searches. Search results are sparse unless Enrich search results is enabled.

## `searchTypes` (type: `array`):

Entity sections to request for each search query.

## `enrichSearchResults` (type: `boolean`):

Fetch each search hit again as a full entity. This is slower and creates more Spotify requests.

## `maxSearchResults` (type: `integer`):

Maximum results per entity type and query.

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

Maximum current snapshot records, including error records. Monitor mode may additionally emit one change record per successful entity.

## `maxTracks` (type: `integer`):

Maximum tracks loaded for each playlist. Album tracklists are fetched by the library as provided by Spotify.

## `maxEpisodes` (type: `integer`):

Maximum episodes loaded for each podcast show.

## `maxConcurrency` (type: `integer`):

Number of entity pipelines allowed to run concurrently. Lower values reduce request pressure.

## `timeoutSecs` (type: `integer`):

Timeout applied to each catalog request.

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

Optional Apify Proxy configuration for Spotify requests.

## Actor input object example

```json
{
  "mode": "snapshot",
  "stateStoreName": "spotify-catalog-monitor",
  "historyDatasetName": "spotify-catalog-history",
  "onlyChanges": false,
  "changePreset": "all_changes",
  "metricThresholdPercent": 0,
  "maxGraphNodes": 1000,
  "rankBy": "monthly_listeners",
  "targets": [
    "https://open.spotify.com/artist/0gxyHStUsqpMadRV0Di1Qt",
    "spotify:track:4uLU6hMCjMI75M1A2tKUQC"
  ],
  "targetType": "auto",
  "searchQueries": [
    "daft punk"
  ],
  "searchTypes": [
    "track",
    "album",
    "artist",
    "playlist",
    "show",
    "episode"
  ],
  "enrichSearchResults": false,
  "maxSearchResults": 20,
  "maxItems": 100,
  "maxTracks": 100,
  "maxEpisodes": 50,
  "maxConcurrency": 5,
  "timeoutSecs": 15,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

## `summary` (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 = {
    "targets": [
        "https://open.spotify.com/artist/0gxyHStUsqpMadRV0Di1Qt",
        "spotify:track:4uLU6hMCjMI75M1A2tKUQC"
    ],
    "searchQueries": [
        "daft punk"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("fetchfinch/spotify-public-catalog-metadata").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 = {
    "targets": [
        "https://open.spotify.com/artist/0gxyHStUsqpMadRV0Di1Qt",
        "spotify:track:4uLU6hMCjMI75M1A2tKUQC",
    ],
    "searchQueries": ["daft punk"],
}

# Run the Actor and wait for it to finish
run = client.actor("fetchfinch/spotify-public-catalog-metadata").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 '{
  "targets": [
    "https://open.spotify.com/artist/0gxyHStUsqpMadRV0Di1Qt",
    "spotify:track:4uLU6hMCjMI75M1A2tKUQC"
  ],
  "searchQueries": [
    "daft punk"
  ]
}' |
apify call fetchfinch/spotify-public-catalog-metadata --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,fetchfinch/spotify-public-catalog-metadata"
        }
    }
}

```

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/C3hcX9ltUetWyWoz6/builds/I2TC3f6Zyw34YtAKi/openapi.json