# Spotify (/docs/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:

```text title="Example"
https://open.spotify.com/artist/06HL4z0CvFAxyc27GXpf02
                                ^^^^^^^^^^^^^^^^^^^^^^
```

```bash title="cURL"
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:

```bash title="cURL"
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.

```bash title="cURL"
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](/docs/computed-fields.md) 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` |

```bash title="cURL"
# 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

## Platform notes

- **Search returns playlists only.** Tracks, artists, albums and podcasts do not appear in results, whatever the query.
- **`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.
- All endpoints use `GET` with query parameters, and responses follow the unified SocialCrawl schema.

## Next steps

- [Apple Music](/docs/apple_music.md): The same catalog reads on the other major streaming service.
- [Computed fields](/docs/computed-fields.md): Formulas, clamping rules, and null semantics.
- [Pagination](/docs/pagination.md): How cursors work across the API.