# Spotify (/docs/spotify)



Spotify [#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 [#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 [#1-fetch-an-artist]

```bash
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:

```bash
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 [#2-walk-a-podcasts-episodes]

```bash
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 [#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](/docs/computed-fields.md) for formulas, clamping rules, and null semantics.

What you can get [#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.

<Callout type="warn">
  **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.
</Callout>

Typical flow [#typical-flow]

```bash
# 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 [#endpoints]

<PlatformEndpoints platform="spotify" />

Notes [#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