Spotify
Spotify artists, tracks, albums, podcast shows, podcast episodes, and playlist search through one unified API
Spotify artists, tracks, albums, podcast shows and their episodes, plus playlist search, all behind the unified SocialCrawl envelope. Every endpoint is a GET and costs 1 credit.
Base URL: /v1/spotify/...
Spotify search returns playlists, and only playlists. Tracks, artists,
albums and podcasts do not come back as results today, whatever the query. To
look up a known song, record, artist or show, call its own endpoint with an
id or url instead. Search will not find it for you.
Quickstart
1. Fetch an artist
Five of the six endpoints are addressed by either an id or a url, and you must supply one of them. Sending neither is a 400 before billing. The id is the segment after the object type in any Spotify link:
https://open.spotify.com/artist/06HL4z0CvFAxyc27GXpf02
^^^^^^^^^^^^^^^^^^^^^^curl "https://www.socialcrawl.dev/v1/spotify/artist?url=https://open.spotify.com/artist/06HL4z0CvFAxyc27GXpf02" \
-H "x-api-key: YOUR_API_KEY"The same call by id:
curl "https://www.socialcrawl.dev/v1/spotify/artist?id=06HL4z0CvFAxyc27GXpf02" \
-H "x-api-key: YOUR_API_KEY"2. Walk a podcast's back catalogue
podcast/episodes is the only paginated endpoint here. Pass the previous response's pagination.next_cursor back to get the next page.
curl "https://www.socialcrawl.dev/v1/spotify/podcast/episodes?id=4rOoJ6Egrf8K2IrywzwOMk" \
-H "x-api-key: YOUR_API_KEY"3. Read computed fields
When an endpoint supports a computed field and the required source inputs are present, the unified response includes that optional field. Depending on the endpoint, optional fields can include engagement_rate, language, content_category, and estimated_reach. See Computed fields for formulas, clamping rules, and null semantics.
Music
| Endpoint | Credits | What it returns | Key parameters |
|---|---|---|---|
GET /v1/spotify/artist | 1 | Id, name, follower count, monthly listeners, genres, and related artists | id or url |
GET /v1/spotify/track | 1 | One song: its artists, album and cover art, duration, play count, and sharing links | id or url |
GET /v1/spotify/album | 1 | A whole record with its release date, copyright, and track list | id or url |
Pick by scope: track for one song, album for the record it sits on, artist for the performer.
Podcasts
Spotify calls podcasts shows, and the URL says /show/ rather than /podcast/.
| Endpoint | Credits | What it returns | Key parameters |
|---|---|---|---|
GET /v1/spotify/podcast | 1 | The show itself: id, name, description, cover art | id or url |
GET /v1/spotify/podcast/episodes | 1 | What the show has published, each episode with a title, release date, duration, cover art, and a short preview audio URL | id or url, cursor |
# 1. The show
curl "https://www.socialcrawl.dev/v1/spotify/podcast?url=https://open.spotify.com/show/4rOoJ6Egrf8K2IrywzwOMk" \
-H "x-api-key: YOUR_API_KEY"
# 2. Its episodes, paging with the cursor from the previous response
curl "https://www.socialcrawl.dev/v1/spotify/podcast/episodes?id=4rOoJ6Egrf8K2IrywzwOMk&cursor=CURSOR_FROM_STEP_1" \
-H "x-api-key: YOUR_API_KEY"Search
| Endpoint | Credits | What it returns | Key parameters |
|---|---|---|---|
GET /v1/spotify/search | 1 | Matching playlists, and only playlists | query |
This is the one endpoint that does not need an id.
All endpoints
6 endpoints available.
| Endpoint | Path | Credit Tier |
|---|---|---|
| Get a Spotify album | /v1/spotify/album | standard (1cr) |
| Get a Spotify artist | /v1/spotify/artist | standard (1cr) |
| Get a Spotify podcast | /v1/spotify/podcast | standard (1cr) |
| List a Spotify podcast's episodes | /v1/spotify/podcast/episodes | standard (1cr) |
| Search Spotify | /v1/spotify/search | standard (1cr) |
| Get a Spotify track | /v1/spotify/track | standard (1cr) |
Platform notes
- Search returns playlists only. Tracks, artists, albums and podcasts do not appear in results, whatever the query.
artist,track,album,podcastandpodcast/episodeseach acceptidorurl. Supply exactly one.searchtakesqueryinstead.- Only
podcast/episodespaginates. The other endpoints return a single object or a fixed set. - All endpoints use
GETwith query parameters, and responses follow the unified SocialCrawl schema.