# Spotify Podcast Show & Episode Metadata Extractor (`vexaloom-labs/spotify-podcast-show-and-episode-metadata`) Actor

Search Spotify podcast shows and episodes, fetch a show's full episode list, resolve a show or episode by link, and browse categories by market - with descriptions, durations, release dates and preview URLs.

- **URL**: https://apify.com/vexaloom-labs/spotify-podcast-show-and-episode-metadata.md
- **Developed by:** [vexaloom-labs](https://apify.com/vexaloom-labs) (community)
- **Categories:** Automation, Developer tools, News
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Spotify Podcast Show & Episode Metadata Extractor

Collect podcast show and episode metadata from Spotify without a Spotify account, client ID or API key. Search the podcast catalog, export a show together with its complete episode archive, resolve a show or episode link, and keep only the release window you need.

The actor reads the same public web-player data that powers Spotify's podcast pages for logged-out visitors. It returns structured records, never audio downloads, and omits empty fields instead of writing `null` placeholders.

### Modes

| Mode | What it returns | Inputs it uses |
|---|---|---|
| `searchShows` | One record per matching podcast show | `searchQuery` |
| `searchEpisodes` | One record per matching episode | `searchQuery` |
| `getShow` | A show record followed by its episode archive | `showIds`, `startUrls` |
| `getEpisode` | One record per episode ID or link | `episodeIds`, `startUrls` |

Search modes page through Spotify's result set until `maxItems` is reached or the source runs out. `getShow` pages through the complete episode archive, not just the first screen.

### Input

| Field | Type | Default | Notes |
|---|---|---|---|
| `mode` | select | `searchShows` | One of the four modes above |
| `searchQuery` | text | `true crime` | Keyword for `searchShows` and `searchEpisodes` |
| `showIds` | string list | empty | Show IDs, `spotify:show:` URIs or show links |
| `episodeIds` | string list | empty | Episode IDs, `spotify:episode:` URIs or episode links |
| `startUrls` | string list | empty | Mixed show/episode links; regional and embed links work |
| `includeDetails` | boolean | `true` | Enriches every search hit with the full show/episode object |
| `includeEpisodes` | boolean | `true` | In `getShow`, export the show's episodes as well |
| `releasedAfter` | text | empty | `YYYY-MM-DD`; older episodes are skipped |
| `releasedBefore` | text | empty | `YYYY-MM-DD`; newer episodes are skipped |
| `maxItems` | integer | `50` | Maximum records to save (1-5000) |

Examples:

```json
{
  "mode": "searchShows",
  "searchQuery": "daily news",
  "maxItems": 25
}
```

```json
{
  "mode": "getShow",
  "startUrls": ["https://open.spotify.com/show/3IM0lmZxpFAY7CwMuv9H4g"],
  "releasedAfter": "2026-01-01",
  "maxItems": 120
}
```

```json
{
  "mode": "getEpisode",
  "episodeIds": ["6cCnimrvXTnb5SIl1jXVtQ"],
  "maxItems": 10
}
```

### Show fields

- `showId` - Spotify show ID
- `name` - show title
- `description`, `descriptionHtml` - plain-text and HTML synopsis
- `publisher` - publisher or creator name
- `mediaType` - `audio` or `video`
- `contentType` - Spotify content type, for example `CONTENT_TYPE_PODCAST`
- `totalEpisodes` - episode count reported by Spotify
- `explicit` - whether Spotify marks the show explicit
- `ratingAverage`, `ratingCount` - show rating and number of ratings
- `topics` - array of `{name, uri}` topic objects
- `images`, `imageUrl` - cover art URLs, largest first
- `externalUrl`, `shareUrl` - canonical Spotify and share links
- `playable`, `playabilityReason` - public playback status
- `consumptionOrder` - Spotify episode ordering, for example `RECENT`
- `showTypes` - Spotify show classifications when present
- `trailer` - trailer episode summary when Spotify exposes one
- `recordType` - always `show`
- `scrapedAt` - ISO 8601 collection timestamp

### Episode fields

- `episodeId` - Spotify episode ID
- `showId`, `showName`, `showImageUrl` - parent show identity
- `name` - episode title
- `description`, `descriptionHtml` - plain-text and HTML episode notes
- `releaseDate` - `YYYY-MM-DD`
- `releaseDateTime` - full ISO 8601 release timestamp
- `releaseDatePrecision` - Spotify precision, for example `MINUTE`
- `durationMs` - episode length in milliseconds
- `explicit`, `contentRating` - content rating information
- `mediaTypes`, `hasVideo` - audio/video classification
- `audioPreviewUrl` - public 30-second preview clip
- `videoPreviewUrl` - video preview when Spotify provides one
- `images`, `imageUrl` - episode artwork URLs, largest first
- `externalUrl`, `shareUrl` - canonical Spotify and share links
- `playable`, `playabilityReason` - public playback status
- `isPaywalled` - whether the episode is paywalled
- `accessBadge` - Spotify access badge when present
- `creator` - creator name when Spotify exposes one
- `isTrailer`, `isNineteenPlus` - episode flags when present
- `transcriptUrl` - transcript link only when the public episode object exposes one
- `recordType` - always `episode`
- `scrapedAt` - ISO 8601 collection timestamp

### Pagination, dates and limits

- Search uses Spotify's offset pagination and stops when the result set is exhausted or `maxItems` is reached.
- `getShow` requests 50 episodes per page and follows Spotify's next offset until the archive ends, `maxItems` records have been saved, or `releasedAfter` passes.
- Episodes are returned newest first by Spotify. `releasedAfter` therefore also stops `getShow` paging early, which keeps large archives inexpensive.
- Search has a practical source ceiling of roughly 1,000 matching items; `getShow` can page through archives several thousand episodes long.
- The public episode object does not expose full transcript text, private subscriber content, or downloadable audio.

### Legacy inputs

The previous version required `clientId` and `clientSecret`. Both are no longer needed and are ignored when an old task still sends them. The old `market` input is also ignored: Spotify decides which catalog is visible from the network location where the actor runs, and Apify cloud runs normally see the US catalog. The former `listCategories` mode has no cookieless equivalent; a saved task that still sends it runs `searchShows` instead and reports that in the status message.

### Data source and scope

- Public Spotify web-player data, read without cookies or login.
- No audio files are downloaded. Preview URLs are metadata links only.
- Podcast catalogs differ by region. Shows that Spotify does not offer in the actor's region can be absent or restricted.
- This is an independent tool and is not affiliated with or endorsed by Spotify.

### FAQ

**Do I need a Spotify developer app?**
No. There is no client ID, client secret, cookie or login step.

**Why are some fields missing from a record?**
Empty values are omitted. Not every publisher supplies a description, rating, topic list, trailer, preview clip or video flag.

**Can I fetch a show and its episodes in one run?**
Yes. Use `mode=getShow`; the run emits one show record and then episodes until `maxItems` records have been saved in total.

**Can I fetch only recent episodes?**
Yes. Set `releasedAfter` and, optionally, `releasedBefore`. In `getShow` the date window also stops paging when the archive is older than the window.

**Can I pass links instead of IDs?**
Yes. `showIds`, `episodeIds` and `startUrls` accept bare IDs, `spotify:` URIs, standard `open.spotify.com` links, regional `/intl-xx/` links and embed links.

**Why does a search return fewer records than `maxItems`?**
Spotify exhausted its public result set for that query, or the date window filtered the remaining episodes. The run status reports what was emitted.

**Are transcripts included?**
Only a transcript link is included when Spotify's public episode object exposes one. Full transcript text is not part of the public payload.

# Actor input Schema

## `mode` (type: `string`):

What to collect from Spotify.

## `searchQuery` (type: `string`):

Keyword to search for in the selected search mode, for example 'true crime', 'daily news' or a host name.

## `showIds` (type: `array`):

Spotify show IDs, spotify:show: URIs or open.spotify.com/show/ links. Used by mode=getShow.

## `episodeIds` (type: `array`):

Spotify episode IDs, spotify:episode: URIs or open.spotify.com/episode/ links. Used by mode=getEpisode.

## `startUrls` (type: `array`):

Mixed show and episode links. Show links are read when mode=getShow, episode links when mode=getEpisode. Regional /intl-xx/ links and embed links are accepted.

## `includeDetails` (type: `boolean`):

Fetch complete show or episode metadata for every search result, including descriptions, ratings, topics, release times, paywall flags and preview audio. Turn off for a faster, lighter search.

## `includeEpisodes` (type: `boolean`):

When mode=getShow, also export the show's episode archive. Turn off to export only the show record.

## `releasedAfter` (type: `string`):

Optional YYYY-MM-DD date. Episodes older than this are skipped. In getShow mode, paging stops once the archive passes this date.

## `releasedBefore` (type: `string`):

Optional YYYY-MM-DD date. Episodes newer than this are skipped.

## `maxItems` (type: `integer`):

Maximum number of show and episode records to save. Search modes have a source ceiling of about 1,000 matching results.

## Actor input object example

```json
{
  "mode": "searchShows",
  "searchQuery": "true crime",
  "showIds": [],
  "episodeIds": [],
  "startUrls": [],
  "includeDetails": true,
  "includeEpisodes": true,
  "releasedAfter": "",
  "releasedBefore": "",
  "maxItems": 3
}
```

# Actor output Schema

## `records` (type: `string`):

Dataset containing show, episode or mixed records depending on the selected mode.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "searchShows",
    "searchQuery": "true crime",
    "showIds": [],
    "episodeIds": [],
    "startUrls": [],
    "includeDetails": true,
    "includeEpisodes": true,
    "releasedAfter": "",
    "releasedBefore": "",
    "maxItems": 3
};

// Run the Actor and wait for it to finish
const run = await client.actor("vexaloom-labs/spotify-podcast-show-and-episode-metadata").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "searchShows",
    "searchQuery": "true crime",
    "showIds": [],
    "episodeIds": [],
    "startUrls": [],
    "includeDetails": True,
    "includeEpisodes": True,
    "releasedAfter": "",
    "releasedBefore": "",
    "maxItems": 3,
}

# Run the Actor and wait for it to finish
run = client.actor("vexaloom-labs/spotify-podcast-show-and-episode-metadata").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "searchShows",
  "searchQuery": "true crime",
  "showIds": [],
  "episodeIds": [],
  "startUrls": [],
  "includeDetails": true,
  "includeEpisodes": true,
  "releasedAfter": "",
  "releasedBefore": "",
  "maxItems": 3
}' |
apify call vexaloom-labs/spotify-podcast-show-and-episode-metadata --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,vexaloom-labs/spotify-podcast-show-and-episode-metadata"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/SH8hDoxwDDjn0zVMr/builds/ArDvL1cbbAWACenMX/openapi.json