Spotify

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/...

Getting Started

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
                                ^^^^^^^^^^^^^^^^^^^^^^

1. Fetch an artist

curl "https://www.socialcrawl.dev/v1/spotify/artist?url=https://open.spotify.com/artist/06HL4z0CvFAxyc27GXpf02" \
  -H "x-api-key: sc_your_api_key_here"

The same call by id:

curl "https://www.socialcrawl.dev/v1/spotify/artist?id=06HL4z0CvFAxyc27GXpf02" \
  -H "x-api-key: sc_your_api_key_here"

2. Walk a podcast's episodes

curl "https://www.socialcrawl.dev/v1/spotify/podcast/episodes?url=https://open.spotify.com/show/4rOoJ6Egrf8K2IrywzwOMk" \
  -H "x-api-key: sc_your_api_key_here"

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.

What you can get

Music. GET /v1/spotify/artist returns an artist's id, name, follower count, monthly listeners, genres, and related artists. GET /v1/spotify/track returns one song — its artists, album and cover art, duration, play count, and sharing links. GET /v1/spotify/album returns a whole record with its release date, copyright, and track list. 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/. GET /v1/spotify/podcast returns the show itself — id, name, description, cover art — and GET /v1/spotify/podcast/episodes lists what it has published, each episode with a title, release date, duration, cover art, and a short preview audio URL. Episodes are the only paginated endpoint here: pass the previous response's cursor back to walk the back catalogue.

Search. GET /v1/spotify/search takes a query and is the one endpoint that does not need an id.

Typical flow

# 1. The show
curl "https://www.socialcrawl.dev/v1/spotify/podcast?url=https://open.spotify.com/show/4rOoJ6Egrf8K2IrywzwOMk" \
  -H "x-api-key: sc_your_api_key_here"

# 2. Its episodes, first page
curl "https://www.socialcrawl.dev/v1/spotify/podcast/episodes?id=4rOoJ6Egrf8K2IrywzwOMk" \
  -H "x-api-key: sc_your_api_key_here"

# 3. Next page — pass back pagination.next_cursor
curl "https://www.socialcrawl.dev/v1/spotify/podcast/episodes?id=4rOoJ6Egrf8K2IrywzwOMk&cursor=CURSOR_FROM_STEP_2" \
  -H "x-api-key: sc_your_api_key_here"

Endpoints

6 endpoints available.

Notes

• All endpoints use GET method with query parameters
• Authentication via x-api-key header
• Responses follow the unified SocialCrawl schema
• artist, track, album, podcast, and podcast/episodes each accept id or url — supply exactly one; search takes query instead
• Only podcast/episodes paginates. The other endpoints return a single object or a fixed set