# Spotify Playlist Search API. Playlists matching your search. Playlists and their curators by keyword. We handle the proxies, blocks and platform changes. [Get API key](https://socialtap.dev/signup/?next=%2Fplayground%2F%3Fendpoint%3Dspotify.search_playlists) ## Spotify Playlist Search API at a glance Searches Spotify's public playlists by keyword in any language and returns them a page at a time, in Spotify's order. Each has its title, description, cover, owner with their username and picture, the kind of list Spotify says it is, and whether its algorithm made it. The Spotify Playlist API adds the follower count, item count and dates. GET `/v1/spotify/search_playlists` [Read the API reference](https://socialtap.dev/docs/reference/spotify/search_playlists/index.md) - **1 credit** per page, $0.75–$1.97 per 1,000 pages - **13 typed fields** null when unknown - **100** playlists per page, Spotify's own ranking for the query - **`query`** is all it needs, e.g. `workout` ## Send one request. Get up to 100 playlists back. Copy the request in your language, or hand it to your agent. Sign up for an API key and your first 100 credits are free. `$ npm install socialtap` `query = workout` [Open in playground](https://socialtap.dev/playground/?endpoint=spotify.search_playlists) cURL: ```shell curl 'https://socialtap.dev/v1/spotify/search_playlists?query=workout' \ -H "x-api-key: $SOCIALTAP_API_KEY" ``` TypeScript SDK: ```typescript import { SocialTap } from "socialtap"; const client = new SocialTap(); // apiKey defaults to process.env.SOCIALTAP_API_KEY const res = await client.spotify.searchPlaylists.list({ query: "workout" }); console.log(res.data); console.log(res.credits.charged, res.meta.request_id); ``` Node.js (fetch): ```javascript const params = new URLSearchParams({ query: "workout", }); const res = await fetch(`https://socialtap.dev/v1/spotify/search_playlists?${params}`, { headers: { "x-api-key": process.env.SOCIALTAP_API_KEY ?? "" }, }); const body = await res.json(); if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`); const { data, page, meta } = body; console.log(data, meta.credits_charged); ``` Python (requests): ```python import os import requests res = requests.get( "https://socialtap.dev/v1/spotify/search_playlists", params={"query": "workout"}, headers={"x-api-key": os.environ["SOCIALTAP_API_KEY"]}, ) body = res.json() if not res.ok: raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}") data, page, meta = body["data"], body["page"], body["meta"] print(data, meta["credits_charged"]) ``` Go (net/http): ```go package main import ( "encoding/json" "fmt" "log" "net/http" "net/url" "os" ) func main() { q := url.Values{} q.Set("query", "workout") req, err := http.NewRequest("GET", "https://socialtap.dev/v1/spotify/search_playlists?"+q.Encode(), nil) if err != nil { log.Fatal(err) } req.Header.Set("x-api-key", os.Getenv("SOCIALTAP_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var body struct { Data json.RawMessage `json:"data"` Page json.RawMessage `json:"page"` Meta map[string]any `json:"meta"` Error *struct { Code string `json:"code"` Message string `json:"message"` } `json:"error"` } if err := json.NewDecoder(res.Body).Decode(&body); err != nil { log.Fatal(err) } if body.Error != nil { log.Fatalf("%s: %s", body.Error.Code, body.Error.Message) } fmt.Println(string(body.Data), body.Meta["credits_charged"]) } ``` 200 OK: ```json { "data": [ { "approximate_fields": [], "description": "Bangers Workout music for you. Also try rap, latin, reggaeton, dance, exotica", "id": "37i9dQZF1EIeNbDmYrgnbS", "is_collaborative": null, "metrics": { "post_count": null }, "owner": { "avatar_url": "https://i.scdn.co/image/ab6775700000ee8555c25988a6ac314394d3fbf5", "display_name": "Spotify", "id": null, "is_verified": null, "url": "https://open.spotify.com/user/spotify", "username": "spotify" }, "platform": "spotify", "platform_specific": { "spotify": { "created_at": null, "follower_count": null, "is_algorithmic": null, "is_collaborative": null, "is_deleted_by_owner": null, "is_user_created": null, "updated_at": null } }, "platform_type": "descripto", "thumbnail_url": "https://seed-mix-image.spotifycdn.com/v6/img/desc/Bangers%20Workout/en/default", "title": "Bangers Workout Mix", "type": "playlist", "unknown_fields": [], "url": "https://open.spotify.com/playlist/37i9dQZF1EIeNbDmYrgnbS" }, { "approximate_fields": [], "description": null, "id": "2rKxqZEf3zcoateybTiJDn", "is_collaborative": null, "metrics": { "post_count": null }, "owner": { "avatar_url": "https://i.scdn.co/image/ab6775700000ee859e5e623e05ef20c32dc9d8bc", "display_name": "PureWow", "id": null, "is_verified": null, "url": "https://open.spotify.com/user/purewow", "username": "purewow" }, "platform": "spotify", "platform_specific": { "spotify": { "created_at": null, "follower_count": null, "is_algorithmic": null, "is_collaborative": null, "is_deleted_by_owner": null, "is_user_created": null, "updated_at": null } }, "platform_type": "playlist", "thumbnail_url": "https://mosaic.scdn.co/640/ab67616d00001e0282db43e5091301205076d6abab67616d00001e02926f43e7cce571e62720fd46ab67616d00001e02b52264e58d9bb36257770a89ab67616d00001e02f9f27162ab1ed45b8d7a7e98", "title": "50 Best Workout Songs That Will Have You *Actually* Breaking a Sweat", "type": "playlist", "unknown_fields": [], "url": "https://open.spotify.com/playlist/2rKxqZEf3zcoateybTiJDn" }, { "approximate_fields": [], "description": "LOCK IN LADIES!!! 💪🏼💸💖🧘🏻‍♀️ Revenge Body So He Regrets It, Hot Girl Walk, Hot Girls Lift Weights, Fitness Girlies, Yoga, Running, Pilates, Treadmill, Cardio, Bad Bitch Workout Playlist, Hot Gym Girls, Hot Girl Workout, BEST GYM SONGS HYPE", "id": "0OxRbscW9gq3FzENFlUPes", "is_collaborative": null, "metrics": { "post_count": null }, "owner": { "avatar_url": "https://i.scdn.co/image/ab6775700000ee850afa00fab7ae8a4c76278e1a", "display_name": "BAD KITTY 😈", "id": null, "is_verified": null, "url": "https://open.spotify.com/user/lqz5moj5fvn3k4mrdg9ewu0g1", "username": "lqz5moj5fvn3k4mrdg9ewu0g1" }, "platform": "spotify", "platform_specific": { "spotify": { "created_at": null, "follower_count": null, "is_algorithmic": null, "is_collaborative": null, "is_deleted_by_owner": null, "is_user_created": null, "updated_at": null } }, "platform_type": "playlist", "thumbnail_url": "https://image-cdn-fa.spotifycdn.com/image/ab67706c0000da847168a8140b4499c5b1322dbd", "title": "HOT GIRL GYM PLAYLIST 🎀🏋🏻‍♀️ Girly Gym Pump, Workout Songs 2026, Beast Mode Baddie Gym Music", "type": "playlist", "unknown_fields": [], "url": "https://open.spotify.com/playlist/0OxRbscW9gq3FzENFlUPes" } ], "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null }, "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "spotify", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 966, "fetched_at": "2026-10-25T12:00:00Z", "input": null, "credits_remaining": 9999, "client_request_id": null, "warnings": [] } } ``` Long arrays and strings are shortened here. Real responses are complete. ## One schema on 6 platforms. The [response reference](https://socialtap.dev/docs/reference/spotify/search_playlists/index.md#response) lists every field, its type and when it is `null`. [See the full schema](https://socialtap.dev/resources/playlist/index.md). - ### Null means unknown A field Spotify doesn't show is null, never zero or an empty string, so a real zero always means zero. - ### What it accepts What to search for, as in Spotify's search box: a playlist's title, a mood, a genre or an artist, in any language. - ### Write one parser Spotify, TikTok, Instagram and 3 more platforms answer in these fields, so the code that reads one reads them all. - **`platform`string**: Platform ID (tiktok, youtube, facebook, …). - **`id`string**: Platform-native playlist ID (string): TikTok's playlist (mix) or collection ID, YouTube's list ID (PL…), Facebook's video list ID. - **`url`string**: Canonical playlist URL. - **`type`string**: playlist: a list its owner curates and orders (TikTok playlists, YouTube playlists, Facebook playlists and series); collection: posts an account saved from any creator into a named public folder (TikTok collections). New values may be added; treat unknown values as playlist. - **`platform_type`string**: The platform's own label, lowercase (mix, collection, playlist, series, podcast, …). - **`title`string**: Name its owner gave it. - **`description`string**: Description as plain text; null when it has none or the platform shows none (TikTok). - **`owner`object**: The account that curates it (for a collection, the account that saved the posts, not their authors). Where a platform's curators are not accounts (Apple Music), what it states of them: a name, perhaps a page and a picture, with id and username null, and every field null when it names no one. Live data from 33 platforms. [TikTok](https://socialtap.dev/apis/tiktok/index.md) · [Instagram](https://socialtap.dev/apis/instagram/index.md) · [Facebook](https://socialtap.dev/apis/facebook/index.md) · [YouTube](https://socialtap.dev/apis/youtube/index.md) · [Reddit](https://socialtap.dev/apis/reddit/index.md) · [Threads](https://socialtap.dev/apis/threads/index.md) · [Spotify](https://socialtap.dev/apis/spotify/index.md) · [Amazon](https://socialtap.dev/apis/amazon/index.md) · [Apple Music](https://socialtap.dev/apis/applemusic/index.md) · [Pinterest](https://socialtap.dev/apis/pinterest/index.md) · [Rumble](https://socialtap.dev/apis/rumble/index.md) · [X](https://socialtap.dev/apis/x/index.md) · [Bluesky](https://socialtap.dev/apis/bluesky/index.md) · [Twitch](https://socialtap.dev/apis/twitch/index.md) · [LinkedIn](https://socialtap.dev/apis/linkedin/index.md) · [Telegram](https://socialtap.dev/apis/telegram/index.md) · [TikTok Shop](https://socialtap.dev/apis/tiktokshop/index.md) · [Kwai](https://socialtap.dev/apis/kwai/index.md) · [Snapchat](https://socialtap.dev/apis/snapchat/index.md) · [SoundCloud](https://socialtap.dev/apis/soundcloud/index.md) · [Truth Social](https://socialtap.dev/apis/truthsocial/index.md) · [Kick](https://socialtap.dev/apis/kick/index.md) · [Komi](https://socialtap.dev/apis/komi/index.md) · [Lnk.Bio](https://socialtap.dev/apis/linkbio/index.md) · [Linkme](https://socialtap.dev/apis/linkme/index.md) · [Linktree](https://socialtap.dev/apis/linktree/index.md) · [Pillar](https://socialtap.dev/apis/pillar/index.md) · [TikTok Ad Library](https://socialtap.dev/apis/tiktok-ad-library/index.md) · [Facebook Ad Library](https://socialtap.dev/apis/facebook-ad-library/index.md) · [Facebook Events](https://socialtap.dev/apis/facebook-events/index.md) · [Facebook Marketplace](https://socialtap.dev/apis/facebook-marketplace/index.md) · [Google Ads Transparency Center](https://socialtap.dev/apis/google-ads-transparency/index.md) · [LinkedIn Ad Library](https://socialtap.dev/apis/linkedin-ad-library/index.md) ## What teams build with the Spotify Playlist Search API. - ### Find curators to pitch a song to - ### Find playlists for a mood or genre - ### Turn a playlist title into its ID ## Good to know before you build. - Results are playlists only: the tracks, artists, albums and podcasts a query matches aren't in the list. - Search lists no item count, follower count, dates or collaborative flag, so metrics.post_count and those platform_specific.spotify fields are null: the Spotify Playlist API returns them. - platform_type is playlist, or Spotify's own name for it when it has one, such as editorial, descripto, inspiredby-mix, topic-mix, artist-mix-reader and artistsets. - title is null on a playlist whose title is empty or only spaces. It is still a real playlist, listed with its ID, link and owner. - is_algorithmic is null where Spotify says neither, as on a listener's playlist. - Results are in Spotify's order, which depends on the page size, so a smaller limit isn't always the top of a larger one. A walk ends with page.end_reason platform_limit where Spotify stops serving, however many it matched. - A page can hold fewer playlists than its limit while next_cursor goes on: repeats from the page before are dropped, and so are playlists Spotify no longer serves or whose owner it no longer names. - A page left with nothing is Spotify failing, not the end of the list: a first page then comes from the fallback below and a later one fails with a retryable error. The exception is a page that goes on with only a few such playlists dropped (limit=1 can hit one), which returns empty with a next_cursor. - Spotify answers a weak query with its nearest guesses, so an empty page is rare and any result may be a loose match. Its music filters return an empty page here, since no playlist has them, and owner: and user: are read as words, so a search can't be narrowed to one owner. - When Spotify's search doesn't answer, the first pages come from a web search engine's index, each playlist read from Spotify, with a partial_data warning, and owner.avatar_url is null. That list holds only what the index has, often a small part of Spotify's, in the engine's order. A next_cursor stays on the list it came from: if Spotify's search stops answering mid-walk, the next page fails with a retryable error instead of switching lists. - An empty query, a Spotify URI or a link to a Spotify page returns invalid_input, naming the endpoint that takes it where there is one. For a link to Spotify's search page, send its words instead. ## 1 credit per page. Failed requests are free. Buy credits once and spend them on any endpoint, on any platform. [Plans and packs](https://socialtap.dev/pricing/index.md) · [How this endpoint is priced](https://socialtap.dev/docs/reference/spotify/search_playlists/index.md#pricing) · [How credits work](https://socialtap.dev/docs/credits/index.md) | Source | Price per successful page | Per 1,000 pages | | --- | --- | --- | | Any source | 1 credit | $0.75–$1.97 | - Cache hits are free. - Credits from packs and top-ups never expire. - A monthly plan's credits are spent first, and what is left of them ends at each renewal. - Prices exclude tax: sales tax is added at checkout where it applies. - Outside the US, plans and packs are sold to businesses: checkout asks for your VAT, GST or other business tax ID. ## Questions about the Spotify Playlist Search API. More in the [API reference](https://socialtap.dev/docs/reference/spotify/search_playlists/index.md). **How much does the Spotify Playlist Search API cost?** A page of up to 100 playlists costs 1 credit. Every successful page is charged, empty pages included. SocialTap credits cost $0.75–$1.97 per 1,000, depending on the plan or pack. **How do I get the next page?** Repeat the same request with cursor set to page.next_cursor from the previous response, keeping the other parameters. When page.has_more is false there are no more pages. Cursors expire after 24 hours. Other platforms ## Playlists on 5 more platforms. - [TikTok Playlists API](https://socialtap.dev/apis/tiktok/playlists/index.md) (1 credit / page · `GET /v1/tiktok/playlists`) - [Instagram Highlights API](https://socialtap.dev/apis/instagram/highlights/index.md) (1 credit / page · `GET /v1/instagram/highlights`) - [Amazon Shop Lists API](https://socialtap.dev/apis/amazon/shop_lists/index.md) (1 credit / page · `GET /v1/amazon/shop_lists`) - [Apple Music Playlist Search API](https://socialtap.dev/apis/applemusic/search_playlists/index.md) (1 credit / page · `GET /v1/applemusic/search_playlists`) - [Pinterest Board API](https://socialtap.dev/apis/pinterest/board/index.md) (1 credit · `GET /v1/pinterest/board`) More Spotify ## Spotify API. 12 endpoints, one key. - [Spotify Track API](https://socialtap.dev/apis/spotify/track/index.md) (1 credit · `GET /v1/spotify/track`) - [Spotify Track Search API](https://socialtap.dev/apis/spotify/search_tracks/index.md) (1 credit / page · `GET /v1/spotify/search_tracks`) - [Spotify Playlist Tracks API](https://socialtap.dev/apis/spotify/playlist_tracks/index.md) (1 credit / page · `GET /v1/spotify/playlist_tracks`) - [Spotify Podcast Episodes API](https://socialtap.dev/apis/spotify/podcast_episodes/index.md) (1 credit / page · `GET /v1/spotify/podcast_episodes`) - [Spotify Artist API](https://socialtap.dev/apis/spotify/artist/index.md) (1 credit · `GET /v1/spotify/artist`) - [Spotify Artist Search API](https://socialtap.dev/apis/spotify/search_artists/index.md) (1 credit / page · `GET /v1/spotify/search_artists`) - [Spotify Playlist API](https://socialtap.dev/apis/spotify/playlist/index.md) (1 credit · `GET /v1/spotify/playlist`) - [Spotify Album API](https://socialtap.dev/apis/spotify/album/index.md) (1 credit · `GET /v1/spotify/album`) - [Spotify Album Search API](https://socialtap.dev/apis/spotify/search_albums/index.md) (1 credit / page · `GET /v1/spotify/search_albums`) - [Spotify Podcast API](https://socialtap.dev/apis/spotify/podcast/index.md) (1 credit · `GET /v1/spotify/podcast`) - [Spotify Podcast Search API](https://socialtap.dev/apis/spotify/search_podcasts/index.md) (1 credit / page · `GET /v1/spotify/search_podcasts`) ## Try it with your own search. Type it in the playground, or copy the request into your code. 100free credits - No credit card - Failed requests are free - Works on all 218 endpoints [Start for free](https://socialtap.dev/signup/) [Read the docs](https://socialtap.dev/docs/index.md) --- [HTML version](https://socialtap.dev/apis/spotify/search_playlists/) · [Docs index for AI agents](https://socialtap.dev/llms.txt) · [All docs in one file](https://socialtap.dev/llms-full.txt)