# Spotify API guide



## Start with Spotify



Discover music, resolve the correct entity type and collect a bounded playlist or podcast sample. Artist, album, track, playlist and show identifiers are not interchangeable.



These requests use your API key and can spend credits. Check the current price on the endpoint page; each new page is a separate request. Later examples use illustrative identifiers: replace them with values from your earlier response.



### 1. Discover an artist



Keep entity types and source IDs alongside names. Search does not guarantee a complete discography. [Parameters and current cost →](https://www.monocrawl.com/docs/endpoints/spotify/search)



**spotify/search**

```
curl "https://www.monocrawl.com/v1/spotify/search?query=Radiohead" \
  -H "x-api-key: mn_your_key_here"
```



### 2. Resolve the artist



Replace the illustrative id with a returned artist ID. Audience counts and popularity are source metrics, not earnings or unique purchasers. [Parameters and current cost →](https://www.monocrawl.com/docs/endpoints/spotify/artist)



**spotify/artist**

```
curl "https://www.monocrawl.com/v1/spotify/artist?id=0cGUm45nv7Z6M6qdXYQGTX" \
  -H "x-api-key: mn_your_key_here"
```



### 3. Inspect a known playlist



Use a playlist ID or URL you intend to inspect. Keep playlist order and any returned continuation rather than sorting all tracks by a popularity field. [Parameters and current cost →](https://www.monocrawl.com/docs/endpoints/spotify/playlist)



**spotify/playlist**

```
curl "https://www.monocrawl.com/v1/spotify/playlist?id=37i9dQZF1DXcBWIGoYBM5M" \
  -H "x-api-key: mn_your_key_here"
```



## Choose filters with the source behavior in mind



| Control | Behavior and limits |
| --- | --- |
| Identity | Store the entity type with the ID; an artist ID cannot be used as a track ID. [Endpoint reference →](https://www.monocrawl.com/docs/endpoints/spotify/artist) |
| Market | Use only a declared market parameter. A missing field can reflect availability rather than a zero metric. [Endpoint reference →](https://www.monocrawl.com/docs/endpoints/spotify/track) |
| Collection bounds | Keep the returned order and continuation; impose a page and credit budget. [Endpoint reference →](https://www.monocrawl.com/docs/endpoints/spotify/playlist) |



Source availability, ordering and field coverage can change. Inspect warnings and partial-result metadata alongside the rows. See [runnable workflows](https://www.monocrawl.com/docs/workflows), [metric semantics](https://www.monocrawl.com/docs/metric-semantics), [computed fields](https://www.monocrawl.com/docs/computed-fields) and the [pagination matrix](https://www.monocrawl.com/docs/pagination).



## Match the operation to your task



| Your task | Endpoint | When to use it |
| --- | --- | --- |
| A known album | [`album`](https://www.monocrawl.com/docs/endpoints/spotify/album) | Use an album ID or URL and a supported market when required by your use case. |
| A known track | [`track`](https://www.monocrawl.com/docs/endpoints/spotify/track) | Keep track and artist IDs separate. Missing playback information does not mean the track does not exist. |
| Podcast episodes | [`podcast/episodes`](https://www.monocrawl.com/docs/endpoints/spotify/podcast/episodes) | Resolve a podcast/show, then use its identifier and the episode endpoint’s own cursor and limit. |



Explore all documented operations by purpose below. Each endpoint reference contains its accepted parameters and current price.



### Other operations



- [`album`](https://www.monocrawl.com/docs/endpoints/spotify/album)

- [`artist`](https://www.monocrawl.com/docs/endpoints/spotify/artist)

- [`podcast`](https://www.monocrawl.com/docs/endpoints/spotify/podcast)

- [`podcast/episodes`](https://www.monocrawl.com/docs/endpoints/spotify/podcast/episodes)

- [`track`](https://www.monocrawl.com/docs/endpoints/spotify/track)



### Posts and media



- [`playlist`](https://www.monocrawl.com/docs/endpoints/spotify/playlist)



### Search and discovery



- [`search`](https://www.monocrawl.com/docs/endpoints/spotify/search)



## Endpoint reference

## spotify/album

`GET /v1/spotify/album`

Look up one Spotify album by id or open.spotify.com URL, including label, copyrights, UPC, and the first page of its track listing.

*Get a Spotify album*

| Parameter | Required | Description |
| --- | --- | --- |
| `id` | no | Spotify album id (this or url) — e.g. `4aawyAB9vmqN3uQ7FjRGTy` |
| `url` | no | open.spotify.com album URL or spotify:album: URI (this or id) — e.g. `https://open.spotify.com/album/4aawyAB9vmqN3uQ7FjRGTy` |
| `market` | no | ISO 3166-1 alpha-2 country to scope availability (optional) — e.g. `US` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/spotify/album?url=https%3A%2F%2Fopen.spotify.com%2Falbum%2F4aawyAB9vmqN3uQ7FjRGTy" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "album_type": "example",
  "artists": [
    {
      "id": "example",
      "name": "example",
      "uri": "example",
      "url": "https://example.com/example"
    }
  ],
  "copyrights": [
    {
      "text": "example",
      "type": "example"
    }
  ],
  "genres": [],
  "id": "example",
  "image_url": "https://example.com/example",
  "images": [
    {
      "height": 0,
      "url": "https://example.com/example",
      "width": 0
    }
  ],
  "kind": "example",
  "label": "example",
  "popularity": 0,
  "release_date": "2026-09-01T12:00:00Z",
  "release_date_precision": "2026-09-01T12:00:00Z",
  "title": "example",
  "total_tracks": 0,
  "uri": "example",
  "url": "https://example.com/example"
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/spotify/album#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/spotify/album.json)


## spotify/artist

`GET /v1/spotify/artist`

One Spotify artist: followers, monthly listeners, world rank, top cities, biography and top tracks with play counts.

*Artist details*

| Parameter | Required | Description |
| --- | --- | --- |
| `id` | yes | Spotify artist id, from spotify/search. — e.g. `0cGUm45nv7Z6M6qdXYQGTX` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 2 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/spotify/artist?id=0cGUm45nv7Z6M6qdXYQGTX" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "biography": "example",
  "followers": 0,
  "id": "example",
  "monthly_listeners": 0,
  "name": "example",
  "platform": "example",
  "popularity": 0,
  "top_cities": [
    {
      "city": "example",
      "country": "example",
      "listeners": 0
    }
  ],
  "top_tracks": [
    {
      "id": "example",
      "name": "example",
      "playcount": 0,
      "popularity": 0,
      "url": "https://example.com/example"
    }
  ],
  "url": "https://example.com/example",
  "verified": false,
  "world_rank": 0
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/spotify/artist#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/spotify/artist.json)


## spotify/playlist

`GET /v1/spotify/playlist`

A public playlist with its owner, follower count and a page of tracks with play counts.

*Spotify playlist*

| Parameter | Required | Description |
| --- | --- | --- |
| `id` | yes | Playlist id (or pass url) — e.g. `37i9dQZF1DXcBWIGoYBM5M` |
| `url` | no | Playlist URL, instead of id — e.g. `https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M` |
| `cursor` | no | Opaque cursor from the previous page of tracks |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `cursor`: Continue the same source traversal with the complete returned cursor. Saved-result retrieval and a new source page can have different prices; quote the next call.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 4 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/spotify/playlist?id=37i9dQZF1DXcBWIGoYBM5M" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "count": 0,
  "description": "example",
  "dropped": 0,
  "followers": 0,
  "id": "example",
  "image_url": "https://example.com/example",
  "items": [
    {
      "album": "example",
      "artists": [
        {}
      ],
      "duration_ms": 0,
      "id": "example",
      "play_count": 0,
      "title": "example",
      "uri": "example",
      "url": "https://example.com/example"
    }
  ],
  "kind": "example",
  "name": "example",
  "owner": {
    "id": "example",
    "name": "example",
    "url": "https://example.com/example"
  },
  "total_tracks": 0,
  "uri": "example",
  "url": "https://example.com/example"
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/spotify/playlist#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/spotify/playlist.json)


## spotify/podcast

`GET /v1/spotify/podcast`

Look up one Spotify podcast (show) by id or open.spotify.com URL: publisher, description, languages, and total episode count.

*Get a Spotify podcast*

| Parameter | Required | Description |
| --- | --- | --- |
| `id` | no | Spotify show id (this or url) — e.g. `38bS44xjbVVZ3No3ByF1dJ` |
| `url` | no | open.spotify.com show URL or spotify:show: URI (this or id) — e.g. `https://open.spotify.com/show/38bS44xjbVVZ3No3ByF1dJ` |
| `market` | no | ISO 3166-1 alpha-2 country; show availability is market-scoped (default US) — e.g. `US` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/spotify/podcast?url=https%3A%2F%2Fopen.spotify.com%2Fshow%2F38bS44xjbVVZ3No3ByF1dJ" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "id": "example",
  "name": "Example podcast",
  "kind": "show"
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/spotify/podcast#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/spotify/podcast.json)


## spotify/podcast/episodes

`GET /v1/spotify/podcast/episodes`

List a Spotify podcast's episodes newest-first, paginated: title, description, duration, release date, and audio preview.

*List a Spotify podcast's episodes*

| Parameter | Required | Description |
| --- | --- | --- |
| `id` | no | Spotify show id (this or url) — e.g. `38bS44xjbVVZ3No3ByF1dJ` |
| `url` | no | open.spotify.com show URL or spotify:show: URI (this or id) — e.g. `https://open.spotify.com/show/38bS44xjbVVZ3No3ByF1dJ` |
| `cursor` | no | Offset for the next page (opaque, from a prior response) — e.g. `25` |
| `limit` | no | Episodes per page, 1-50 (default 25) — e.g. `25` |
| `market` | no | ISO 3166-1 alpha-2 country; episode availability is market-scoped (default US) — e.g. `US` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `limit`: Bound the returned rows to what your task needs. A smaller limit does not necessarily reduce source calls or price; inspect the quote.
- `cursor`: Continue the same source traversal with the complete returned cursor. Saved-result retrieval and a new source page can have different prices; quote the next call.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/spotify/podcast/episodes?url=https%3A%2F%2Fopen.spotify.com%2Fshow%2F38bS44xjbVVZ3No3ByF1dJ" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "_meta": {
    "billing": {
      "charged": 0,
      "list_price": 0,
      "reason": "example"
    }
  },
  "dropped": 0,
  "items": []
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/spotify/podcast/episodes#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/spotify/podcast/episodes.json)


## spotify/search

`GET /v1/spotify/search`

Search the Spotify catalog: matching artists, tracks, albums and playlists with ids and links.

*Catalog search*

| Parameter | Required | Description |
| --- | --- | --- |
| `query` | yes | Artist, track, album or playlist name. — e.g. `daft punk` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 2 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/spotify/search?query=daft%20punk" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "albums": [
    {
      "artist": "example",
      "id": "example",
      "name": "example",
      "type": "example",
      "url": "https://example.com/example",
      "year": 0
    }
  ],
  "artists": [
    {
      "id": "example",
      "name": "example",
      "url": "https://example.com/example",
      "verified": false
    }
  ],
  "playlists": [
    {
      "description": "example",
      "id": "example",
      "name": "example",
      "url": "https://example.com/example"
    }
  ],
  "tracks": [
    {
      "album": "example",
      "artist": "example",
      "duration_ms": 0,
      "id": "example",
      "name": "example",
      "url": "https://example.com/example"
    }
  ]
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/spotify/search#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/spotify/search.json)


## spotify/track

`GET /v1/spotify/track`

Look up one Spotify track by id or open.spotify.com URL, with ISRC, duration, artists, and album context.

*Get a Spotify track*

| Parameter | Required | Description |
| --- | --- | --- |
| `id` | no | Spotify track id (this or url) — e.g. `11dFghVXANMlKmJXsNCbNl` |
| `url` | no | open.spotify.com track URL or spotify:track: URI (this or id) — e.g. `https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl` |
| `market` | no | ISO 3166-1 alpha-2 country to scope availability (optional) — e.g. `US` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/spotify/track?url=https%3A%2F%2Fopen.spotify.com%2Ftrack%2F11dFghVXANMlKmJXsNCbNl" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "album": {
    "album_type": "example",
    "artists": [],
    "id": "example",
    "image_url": "https://example.com/example",
    "release_date": "2026-09-01T12:00:00Z",
    "title": "example",
    "total_tracks": 0,
    "uri": "example",
    "url": "https://example.com/example"
  },
  "artists": [
    {
      "id": "example",
      "name": "example",
      "uri": "example",
      "url": "https://example.com/example"
    }
  ],
  "duration_ms": 0,
  "explicit": false,
  "id": "example",
  "kind": "example",
  "play_count": 0,
  "popularity": 0,
  "title": "example",
  "track_number": 0,
  "uri": "example",
  "url": "https://example.com/example"
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/spotify/track#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/spotify/track.json)