Spotify APIspotify.com ↗
Search Spotify's music catalog and retrieve artist profiles, top tracks, discography, follower counts, monthly listeners, and top cities via two API endpoints.
What is the Spotify API?
The Spotify API provides two endpoints — search and get_artist — giving programmatic access to Spotify's music catalog and detailed artist intelligence. A single search call returns up to 50 results each across tracks, albums, artists, playlists, and podcasts. get_artist returns 15+ fields per artist including biography, follower count, monthly listener data, top tracks, full discography, and top listener cities.
curl -X POST 'https://api.parse.bot/scraper/143b411a-341f-40ea-90ca-b73c6cdbb436/search' \
-H 'X-API-Key: $PARSE_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"type": "all",
"limit": "5",
"query": "Adele",
"offset": "0"
}'Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace spotify-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Spotify Music Library SDK — search catalog and explore artists."""
from parse_apis.spotify_com_api import Spotify, ContentType, ArtistNotFound
client = Spotify()
# Search for tracks by a popular artist, capped at 5 results.
for track in client.catalogs.search(query="Adele", type=ContentType.TRACKS, limit=5):
print(track.name, track.artists, track.duration_ms)
# Get a specific artist's full profile by ID (from a search result).
results = client.catalogs.search(query="Taylor Swift", type=ContentType.ARTISTS, limit=1)
artist_summary = results.first()
if artist_summary:
full_artist = artist_summary.details()
print(full_artist.name, full_artist.monthly_listeners, full_artist.followers)
for city in full_artist.top_cities:
print(city.city, city.country, city.listeners)
# Browse an artist's top tracks via the artists collection.
if artist_summary:
top = client.artists.get(artist_id=artist_summary.id, limit=3)
for track in top:
print(track.name, track.playcount)
# Typed error handling: attempt to get a non-existent artist.
try:
client.artists.get(artist_id="does_not_exist_xyz", limit=1).first()
except ArtistNotFound as exc:
print(f"Artist not found: {exc.artist_id}")
print("exercised: catalogs.search / artist_summary.details / artists.get / error handling")
Full-text search across Spotify's music catalog. Returns tracks, artists, albums, playlists, and podcasts matching the query. Results can be filtered by content type and paginated via offset. Each result category returns up to `limit` items per request.
| Param | Type | Description |
|---|---|---|
| type | string | Filter results to a specific content type. Omitted or 'all' returns all types. |
| limit | integer | Maximum number of results per content type (1-50). |
| queryrequired | string | Search query string (artist name, track title, album, etc.). |
| offset | integer | Offset for pagination within each content type. |
{
"type": "object",
"fields": {
"query": "string",
"albums": "array of album objects with id, name, artists, year, type, image_url, uri",
"tracks": "array of track objects with id, name, artists, album_name, duration_ms, image_url, uri",
"artists": "array of artist objects with id, name, image_url, uri",
"podcasts": "array of podcast objects with id, name, publisher, description, image_url, uri",
"playlists": "array of playlist objects with id, name, description, owner, image_url, uri",
"type_filter": "string"
},
"sample": {
"data": {
"query": "Taylor Swift",
"albums": [
{
"id": "4a6NzYL1YHRUgx9e3YZI6I",
"uri": "spotify:album:4a6NzYL1YHRUgx9e3YZI6I",
"name": "The Life of a Showgirl",
"type": "ALBUM",
"year": 2025,
"artists": [
"Taylor Swift"
],
"image_url": "https://i.scdn.co/image/ab67616d00001e02d7812467811a7da6e6a44902"
}
],
"tracks": [
{
"id": "53iuhJlwXhSER5J2IYYv1W",
"uri": "spotify:track:53iuhJlwXhSER5J2IYYv1W",
"name": "The Fate of Ophelia",
"artists": [
"Taylor Swift"
],
"image_url": "https://i.scdn.co/image/ab67616d00001e02d7812467811a7da6e6a44902",
"album_name": "The Life of a Showgirl",
"duration_ms": 226073
}
],
"artists": [
{
"id": "06HL4z0CvFAxyc27GXpf02",
"uri": "spotify:artist:06HL4z0CvFAxyc27GXpf02",
"name": "Taylor Swift",
"image_url": "https://i.scdn.co/image/ab6761610000e5ebe2e8e7ff002a4afda1c7147e"
}
],
"podcasts": [
{
"id": "57chMWWvJOZlwLEPZyxXKg",
"uri": "spotify:show:57chMWWvJOZlwLEPZyxXKg",
"name": "13: A Taylor Swift Fan Podcast",
"image_url": "https://i.scdn.co/image/ab6765630000f68d03e8bd9c6e7656b14efd2602",
"publisher": "Jane Doe",
"description": null
}
],
"playlists": [
{
"id": "0Y44bc2Fd2IfbhqSPnNlTC",
"uri": "spotify:playlist:0Y44bc2Fd2IfbhqSPnNlTC",
"name": "Taylor Swift: Hits and Best of",
"owner": "John Doe",
"image_url": "https://mosaic.scdn.co/640/ab67616d00001e025076e4160d018e378f488c33",
"description": "greatest songs"
}
],
"type_filter": "all"
},
"status": "success"
}
}About the Spotify API
Search the Spotify Catalog
The search endpoint accepts a query string and returns matching results across five content types: tracks, albums, artists, playlists, and podcasts. You can narrow results to a single type using the type parameter, paginate through large result sets with offset, and control how many results come back per type with limit (1–50). Each track result includes duration_ms, the associated album name, artist list, and a direct uri for deep-linking. Album results carry the release year and type field (album, single, compilation). Podcast results include publisher and a description field.
Artist Profiles and Statistics
The get_artist endpoint accepts a 22-character Spotify artist_id — obtainable directly from search results — and returns a full artist record. Numeric audience data includes followers and per-city listener counts via the top_cities array, where each entry contains city, country, and listeners. The biography field carries the artist's editorial text. Discography is split into albums and singles arrays; each release includes id, name, year, total_tracks, type, image_url, and uri.
Coverage and Pagination
Both endpoints reflect Spotify's catalog as it appears publicly. The search endpoint supports pagination via offset, so iterating through large result sets is straightforward. Artist IDs returned in search results can be fed directly into get_artist, making the two endpoints composable for catalog traversal or artist research workflows.
The Spotify API is a managed, monitored endpoint for spotify.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when spotify.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official spotify.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a music discovery app that surfaces related artists and their top listener cities using
get_artistdata. - Aggregate follower and monthly listener counts across a roster of artists for talent management dashboards.
- Power autocomplete search for tracks and albums in a music app using the
searchendpoint withtypefiltering. - Pull full discographies (albums and singles arrays) to populate artist profile pages with release timelines.
- Research podcast catalog coverage by querying publisher and description fields from podcast search results.
- Feed artist biography and verified status into editorial content management systems for music journalism tools.
- Build playlist metadata collectors by searching by name and retrieving owner and description fields.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Spotify have an official developer API?+
What does `get_artist` return that the search artist results do not?+
search endpoint returns a lightweight artist object with id, name, image_url, and uri. get_artist expands this into a full record including biography, followers, verified status, top_cities with per-city listener counts, separate albums and singles arrays, and linked external resources.Can I retrieve top tracks or play counts for an artist?+
get_artist's return data, but the documented response fields above focus on discography, cities, biography, and follower counts. If you need play count fields explicitly in the response schema, you can fork this API on Parse and revise it to surface those fields.Does the search endpoint return audio features like tempo, key, or energy for tracks?+
id, name, artists, album_name, duration_ms, image_url, and uri. Audio features are not part of the current response. You can fork the API on Parse and revise it to add an endpoint that returns audio analysis data.How do I paginate through more than 50 search results?+
offset parameter to the number of results already retrieved and repeat the request with the same query and type. For example, to get the second page of 50 tracks, set offset to 50 and limit to 50. Each content type is paginated independently.