---
title: "Scrape Spotify artists, albums, tracks, playlists and search"
method: POST
path: "/music/spotify"
tags: ["Plugins"]
---

# Scrape Spotify artists, albums, tracks, playlists and search

`POST /music/spotify`

## Request

- Base URL: `https://api.scrapeunblocker.com`
- URL: `https://api.scrapeunblocker.com/music/spotify`
- Auth: API key in header `x-scrapeunblocker-key`

Returns Spotify catalog data as JSON, including the play counts and audience numbers the official Web API does not expose. `type=artist`: `artist` (`followers`, `monthlyListeners`, `worldRank`, `topCities`, `biography`, `externalLinks`, images, `verified`), `topTracks` with `playcount` (a top track's `album` carries `name` and `releaseDate` when Spotify lists that album among the artist's releases), `discography` groups (popular releases, albums, singles, compilations with totals), `relatedArtists`, `appearsOn`, `featuredOn` / `discoveredOn` playlists; `discography=true` adds the full `releases` list, paged. `type=album`: `album` (type, release date, label, copyright, artists, cover) and `tracks` with `playcount`, paged. `type=track`: `track` with `playcount`, duration, explicit flag, album and every credited artist. `type=playlist`: `playlist` (name, description, `followers`, owner, cover, `totalTracks`) and `tracks` with `playcount`, `addedAt`, `bpm` and `key`, paged. `type=search&query=`: `results` of `search_type` tracks, artists, albums or playlists, paged; a search with no match answers 200 with empty `results`. `playcount` comes only on artist, album, track and playlist lookups: Spotify's search does not return it, so search track results have no `playcount` key (look a track up with `type=track` for its count). `id` takes an open.spotify.com URL, a Spotify URI or a bare id. Lists page with `offset` / `max_results` and answer `hasMore` / `nextOffset`; each page fetched is one billed unit (`pagesFetched`).

## Query parameters

- `type` string, nullable: What to fetch: artist, album, track, playlist, search. Optional when `id` is a Spotify URL or URI (they carry the type) or when only `query` is given (a search).
- `id` string, nullable: The artist, album, track or playlist: an open.spotify.com URL (https://open.spotify.com/artist/06HL4z0CvFAxyc27GXpf02), a Spotify URI (spotify:artist:06HL4z0CvFAxyc27GXpf02) or a bare 22-character id (then set `type`).
- `query` string, nullable: Search text for type=search, e.g. 'daft punk'.
- `search_type` string: What a search returns: tracks, artists, albums, playlists.
- `offset` integer: 0-based position to start from in the list being paged: album tracks, playlist tracks, search results, or the full discography with discography=true. Use the `nextOffset` of a previous response to continue. Spotify serves search results up to position 1000.
- `max_results` integer, nullable: How many list items to collect. Album tracks: 1-1000 (default 100, 100 per page). Playlist tracks: 1-2000 (default 100, 100 per page). Search: 1-1000 (default 20, 50 per page). Artist releases with discography=true: 1-1000 (default 50, 50 per page). Each page fetched is one billed unit.
- `discography` boolean: type=artist only: also return the artist's full release list (albums, singles, compilations, newest first) in `releases`, paged by offset / max_results.
- `proxy_country` string, nullable: Country the request is sent from (ISO-2, e.g. 'DE', 'GB'). Spotify's market follows it, which can change `playable` and search order; play counts are the same everywhere. Leave blank for any.

## Response `200`

JSON with `type` and the entity (`artist`, `album`, `track` or `playlist`) plus its lists, or `results` for a search.

- unknown

## Other responses

- `400`: Invalid parameters.
- `404`: Spotify has no artist, album, track or playlist with that id (a private playlist reads as not found).
- `422`: Validation Error
- `502`: Spotify refused the request, returned no data, or did not answer in time.

---

[API](https://skmtc.dev/scrapeunblocker/apis/scrapeunblocker-api.md) · [All operations](https://skmtc.dev/scrapeunblocker/apis/scrapeunblocker-api/llms.txt) · [OpenAPI document](https://skmtc.dev/scrapeunblocker/apis/scrapeunblocker-api/revisions/c02f1254cc47?raw)