# Spotify Album Metadata and Artwork Scraper (`automation-lab/spotify-album-metadata-artwork`) Actor

Resolve public Spotify album URLs or IDs into album metadata, artists, release details, label and rights context, cover-art sizes, and normalized track rows.

- **URL**: https://apify.com/automation-lab/spotify-album-metadata-artwork.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** For creators
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.08 / 1,000 item extracteds

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 Album Metadata and Artwork Scraper

Extract **Spotify album metadata and artwork** from public album URLs or IDs. Each dataset item combines album identity, artists, exact release date, record-label/copyright context, every available cover-art size, canonical links, and a normalized nested track listing.

Supply one album for an artwork lookup or a list of albums for recurring music-catalog enrichment. No Spotify login, cookies, developer application, or API credential is required.

### What can you extract?

| Data | Examples |
| --- | --- |
| Album identity | Spotify ID, URI, URL, name, album type |
| Artists | Normalized album artist names |
| Release details | Exact release date and release year |
| Rights context | Public label and copyright text |
| Catalog summary | Track count, total duration, explicit and playable flags |
| Cover artwork | All exposed image URLs with width and height |
| Track rows | Position, disc/track number, ID, name, artists, duration, flags, preview URL |
| External links | Canonical Spotify album and track URLs |

Artwork files themselves are not downloaded. The output contains stable Spotify CDN image URLs and dimensions so your pipeline can select the needed size.

### Who is this Spotify album extractor for?

- Music catalog teams enriching album IDs from a source spreadsheet.
- Developers normalizing public album and track data for an application.
- Designers and editorial teams retrieving available cover-art variants.
- Labels and researchers comparing publicly exposed release and rights metadata over time.
- Data engineers sending consistent Spotify album records to a warehouse, sheet, or webhook.

### Why use this Actor?

The Actor accepts both album URLs and bare IDs, removes duplicates, and emits one integration-friendly album record per unique input. Tracks and artwork are included inside that record with no separate per-track charge. It uses lightweight public Spotify surfaces rather than a browser, making small recurring catalog jobs fast and economical.

The parser fails visibly when Spotify changes the expected structured response. It does not convert blocked or malformed pages into misleading empty records.

### How to get started

1. Open the Actor in Apify Console.
2. Add one or more public Spotify album URLs or 22-character album IDs.
3. Keep **Include normalized tracks** enabled for catalog enrichment.
4. Set **Maximum albums** if you want to process only the first part of a supplied list.
5. Click **Start**.
6. Open the default dataset, then export JSON, CSV, Excel, XML, or RSS.

A working input:

```json
{
  "albumUrlsOrIds": [
    "https://open.spotify.com/album/4aawyAB9vmqN3uQ7FjRGTy",
    "0Lg1uZvI312TPqxNWShFXL"
  ],
  "includeTracks": true,
  "maxAlbums": 100
}
```

### Input parameters

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `albumUrlsOrIds` | array | example Spotify album | Required public album URLs or bare 22-character IDs; duplicates are removed |
| `maxAlbums` | integer | `100` | Maximum unique supplied albums to process, from 1 to 1,000 |
| `includeTracks` | boolean | `true` | Include normalized nested track rows; disable for album/artwork-only output |

Only Spotify **album** URLs and IDs are accepted. Playlist, artist, episode, show, and track URLs fail input validation instead of producing a false album record.

### Output example

The default dataset contains one item per album. This shortened example comes from the prefilled public album:

```json
{
  "spotifyId": "4aawyAB9vmqN3uQ7FjRGTy",
  "spotifyUri": "spotify:album:4aawyAB9vmqN3uQ7FjRGTy",
  "spotifyUrl": "https://open.spotify.com/album/4aawyAB9vmqN3uQ7FjRGTy",
  "name": "Global Warming",
  "artists": ["Pitbull"],
  "releaseDate": "2012-11-16",
  "releaseYear": 2012,
  "label": "RCA Records, a division of Sony Music Entertainment",
  "totalTracks": 18,
  "artwork": [
    {
      "url": "https://image-cdn-fa.spotifycdn.com/image/...",
      "width": 300,
      "height": 300
    }
  ],
  "tracks": [
    {
      "position": 1,
      "discNumber": 1,
      "trackNumber": 1,
      "spotifyId": "6OmhkSOpvYBokMKQxpIGx2",
      "name": "Global Warming (feat. Sensato)",
      "artists": ["Pitbull", "Sensato"],
      "durationMs": 85400,
      "explicit": true,
      "playable": true
    }
  ]
}
```

Nullable fields such as `releaseDate`, `label`, `playable`, or `previewUrl` are `null` when Spotify does not publicly expose them. Popularity is intentionally not claimed because it is not consistently exposed by the supported anonymous album surfaces.

### How much does it cost to extract Spotify albums?

The Actor uses pay-per-event pricing:

- a **$0.00005** one-time run-start event;
- one `Item extracted` event per unique Spotify album saved;
- nested tracks and artwork have no separate charge.

At the BRONZE tier the current per-album price is **$0.001796**. Example totals are approximately:

| Albums | Estimated total |
| ---: | ---: |
| 1 | $0.001846 |
| 10 | $0.01801 |
| 100 | $0.17965 |

Your subscription tier can apply a lower per-album event price. Failed inputs and albums that are not saved do not create an album event.

### Catalog enrichment workflow

For a repeatable enrichment job:

1. Export album IDs from your catalog database.
2. Pass them to `albumUrlsOrIds` on a scheduled Task.
3. Use Spotify ID as the stable merge key.
4. Flatten `tracks` or `artwork` downstream only when your destination requires rows.
5. Store `scrapedAt` to compare later snapshots.

The Actor does not maintain history itself. Apify schedules and dataset retention let you build snapshots without an always-on service.

### Artwork retrieval workflow

Use `artwork[].width` and `artwork[].height` to choose the closest available image variant. Keep `includeTracks: false` when only album identity and artwork are needed. Respect Spotify's terms and the rights attached to each image; a public image URL is not a license to republish artwork.

### Integrations and exports

Dataset results work with Apify integrations and standard exports:

- download JSON, JSONL, CSV, Excel, XML, or RSS;
- send completed runs through webhooks;
- connect Google Sheets or Zapier;
- retrieve dataset items from the Apify API;
- load nested JSON into a warehouse or transformation job.

CSV exports serialize nested arrays. Use JSON or JSONL when you need complete track and artwork structures.

### Run through the Apify API with cURL

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~spotify-album-metadata-artwork/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "albumUrlsOrIds": ["4aawyAB9vmqN3uQ7FjRGTy"],
    "includeTracks": true,
    "maxAlbums": 1
  }'
```

Use the returned run's `defaultDatasetId` to retrieve items after completion.

### JavaScript API example

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/spotify-album-metadata-artwork').call({
  albumUrlsOrIds: ['https://open.spotify.com/album/0Lg1uZvI312TPqxNWShFXL'],
  includeTracks: true,
  maxAlbums: 1,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items[0].name, items[0].artwork);
```

### Python API example

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('automation-lab/spotify-album-metadata-artwork').call(run_input={
    'albumUrlsOrIds': ['0Lg1uZvI312TPqxNWShFXL'],
    'includeTracks': True,
    'maxAlbums': 1,
})
items = list(client.dataset(run['defaultDatasetId']).iterate_items())
print(items[0]['name'], items[0]['tracks'][0])
```

### Use with MCP and AI agents

#### Claude Code setup

Add the Actor to Claude Code:

```bash
claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/spotify-album-metadata-artwork"
```

#### Claude Desktop setup

Use this JSON in Claude Desktop's MCP configuration. The same remote-server URL also works for **Cursor setup** and **VS Code setup** in clients that support HTTP MCP servers:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/spotify-album-metadata-artwork"
    }
  }
}
```

Example prompts:

- “Extract metadata, all cover sizes, and tracks for these Spotify album URLs.”
- “Resolve these album IDs and return the largest artwork URL for each.”
- “Compare release dates and labels from this week's album catalog snapshot.”

### Reliability, retries, and limits

The Actor makes two lightweight public HTML requests per album. Transient network errors, HTTP 429 responses, and server errors receive up to three bounded attempts with backoff. Deterministic invalid input and not-found responses are not blindly retried.

For a multi-album input, one exhausted album is logged and the remaining albums continue. If no album can be extracted, the run fails. The maximum input and processing cap is 1,000 albums per run. Spotify can change public fields, regional playability, previews, or image hosts without notice.

### Troubleshooting

**Why did my input fail immediately?**

Confirm that every value is either a public `open.spotify.com/album/...` URL or a 22-character Spotify album ID. Remove track, playlist, artist, and shortened redirect URLs.

**Why is a field null?**

Spotify does not expose every release field for every album or market. Null is different from an empty string and means the supported public surface did not provide that value.

**Why is a preview URL missing?**

Audio previews and playability vary by track, licensing, and market. The Actor reports the public value but cannot create a preview that Spotify does not expose.

### Legal and responsible use

This Actor extracts publicly accessible metadata. You are responsible for complying with Spotify's terms, applicable copyright and database rights, privacy law, and the rules of your destination system. Do not use it to bypass access controls, download audio, impersonate users, or republish copyrighted artwork without permission. Keep request volumes reasonable and collect only what your legitimate workflow needs.

### FAQ

**Does it require a Spotify account or developer token?**\
No. It uses public anonymous album and embed surfaces.

**Does it download songs or cover files?**\
No. It returns metadata, preview links when exposed, and artwork URLs/dimensions.

**Can it search Spotify by artist or album name?**\
No. This focused Actor resolves supplied album URLs or IDs. It does not claim keyword search.

**Are tracks charged separately?**\
No. One album event includes all exposed nested track rows and artwork variants.

**Can I schedule it?**\
Yes. Create an Apify Task and attach a schedule for repeat snapshots or catalog enrichment.

### Related Actors from automation-lab

- [Spotify Playlist Search and Metadata Scraper](https://apify.com/automation-lab/spotify-playlist-search-scraper) for playlist discovery and playlist track context.
- [Spotify Podcast and Episode Search Scraper](https://apify.com/automation-lab/spotify-podcast-episode-search) for shows and episodes rather than music albums.

These products cover different Spotify entity types and do not replace this supplied-album metadata and artwork workflow.

# Actor input Schema

## `albumUrlsOrIds` (type: `array`):

Public Spotify album URLs or 22-character album IDs. Duplicates are removed.

## `maxAlbums` (type: `integer`):

Maximum number of unique supplied albums to extract.

## `includeTracks` (type: `boolean`):

Include nested track rows with artist names, duration, explicit/playable flags, preview URL, and position.

## Actor input object example

```json
{
  "albumUrlsOrIds": [
    "https://open.spotify.com/album/4aawyAB9vmqN3uQ7FjRGTy"
  ],
  "maxAlbums": 100,
  "includeTracks": true
}
```

# Actor output Schema

## `overview` (type: `string`):

Default dataset containing normalized Spotify album metadata, artwork variants, and optional nested track rows.

# 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 = {
    "albumUrlsOrIds": [
        "https://open.spotify.com/album/4aawyAB9vmqN3uQ7FjRGTy"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/spotify-album-metadata-artwork").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 = { "albumUrlsOrIds": ["https://open.spotify.com/album/4aawyAB9vmqN3uQ7FjRGTy"] }

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/spotify-album-metadata-artwork").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 '{
  "albumUrlsOrIds": [
    "https://open.spotify.com/album/4aawyAB9vmqN3uQ7FjRGTy"
  ]
}' |
apify call automation-lab/spotify-album-metadata-artwork --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/spotify-album-metadata-artwork"
        }
    }
}

```

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/hKLCkWs28oZpfpyFo/builds/lLmpvRCxesnAqbx44/openapi.json