# Spotify Podcast and Episode Search Scraper (`automation-lab/spotify-podcast-episode-search`) Actor

Search public Spotify podcasts and episodes by keyword and export show, publisher, publication date, duration, artwork, and canonical link metadata.

- **URL**: https://apify.com/automation-lab/spotify-podcast-episode-search.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** Social media
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

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

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Spotify Podcast and Episode Search Scraper

Search Spotify's public podcast catalog by keyword and export clean podcast and episode metadata.

The Actor turns Spotify search results into structured rows for podcast research, sponsorship discovery, guest prospecting, topic analysis, and scheduled monitoring.

It does not require a Spotify login or developer API credentials.

### What can Spotify Podcast and Episode Search Scraper do?

- Search podcast shows by topic or keyword.
- Search individual podcast episodes by topic or keyword.
- Return shows and episodes together in one run.
- Accept public Spotify `/search/.../podcasts` and `/search/.../episodes` URLs.
- Paginate beyond the first visible search screen.
- Deduplicate records by canonical Spotify URI.
- Stop at a user-controlled result limit.
- Export JSON, CSV, Excel, XML, RSS, or JSONL through Apify datasets.
- Run on a schedule for repeatable podcast research.

This is a search product, not a chart scraper.
For ranked market and genre charts, use our related Spotify Podcast Charts Scraper.

### Who is this Spotify podcast search for?

**Podcast networks and publishers** can discover adjacent shows and episodes around a programming theme.

**Sponsorship and PR teams** can build public show and publisher lists for manual qualification.

**Guest researchers** can identify relevant episodes, parent shows, and canonical links.

**Content strategists** can compare which episodes Spotify surfaces for recurring topics.

**Data teams** can schedule the same searches and feed normalized rows into warehouses, spreadsheets, or dashboards.

### Why use this Actor?

Spotify's search interface is designed for interactive browsing rather than repeatable exports.
This Actor provides:

1. one input contract for podcast and episode searches;
2. consistent fields across repeated runs;
3. bounded pagination and deduplication;
4. clear failures instead of silently returning an empty dataset after an upstream change;
5. Apify scheduling, integrations, webhooks, API access, and MCP support.

Only public metadata surfaced by Spotify search is returned.

### What data does it extract?

| Field | Meaning |
| --- | --- |
| `recordType` | `podcast` or `episode` |
| `spotifyId` | Spotify ID for the result |
| `uri` | Canonical Spotify URI |
| `url` | Canonical public Spotify result URL |
| `name` | Show or episode title |
| `description` | Episode description when surfaced |
| `publisher` | Podcast publisher or creator |
| `showName` | Parent show name |
| `showId` | Parent Spotify show ID |
| `showUrl` | Parent show URL |
| `releaseDate` | Episode publication timestamp when surfaced |
| `durationMs` | Episode duration in milliseconds |
| `durationSeconds` | Rounded episode duration in seconds |
| `explicit` | Spotify explicit-content marker when available |
| `mediaTypes` | Surfaced formats such as `AUDIO`, `VIDEO`, or `MIXED` |
| `imageUrl` | Largest artwork image surfaced in search |
| `query` | Search term that produced the row |
| `position` | Position within the query and record type |
| `scrapedAt` | Collection timestamp |

Fields unavailable for a record type are returned as `null` or an empty array.
For example, podcast search rows normally do not include an episode duration.

### How to search Spotify podcasts and episodes

1. Open the Actor input page.
2. Add one or more terms under **Search queries**.
3. Choose **Podcasts and episodes**, **Podcasts only**, or **Episodes only**.
4. Set **Maximum results**.
5. Click **Start**.
6. Open the default dataset to preview or export results.

A useful first input is:

```json
{
  "queries": ["artificial intelligence"],
  "mode": "both",
  "maxItems": 20
}
```

This returns a balanced sample of public podcast shows and episodes for the topic.

### Input parameters

#### `queries`

An array of non-empty search phrases.
Examples include `artificial intelligence`, `climate change`, and `renewable energy`.

#### `searchUrls`

Optional public Spotify search URLs.
Supported forms are:

```text
https://open.spotify.com/search/technology/podcasts
https://open.spotify.com/search/technology/episodes
```

The URL's final path segment controls its record type.
Other Spotify pages, hosts, and paths fail input validation.

#### `mode`

Controls query inputs:

- `both` searches podcast shows and episodes;
- `podcasts` searches shows only;
- `episodes` searches episodes only.

A source-specific `searchUrls` entry keeps the type encoded in that URL.

#### `maxItems`

The maximum number of unique rows saved across the run.
Allowed values are 1–1,000.
When several query/type jobs are requested, the Actor divides the available limit across them so one type does not starve the others.

### Output example

A current episode result has this shape:

```json
{
  "recordType": "episode",
  "spotifyId": "0BGcaYvcDPkvBzFmkRI5uY",
  "uri": "spotify:episode:0BGcaYvcDPkvBzFmkRI5uY",
  "url": "https://open.spotify.com/episode/0BGcaYvcDPkvBzFmkRI5uY",
  "name": "#494 – Jensen Huang: NVIDIA - The $4 Trillion Company & the AI Revolution",
  "publisher": "Lex Fridman",
  "showName": "Lex Fridman Podcast",
  "showId": "2MAi0BvDc6GTFvKFPXnkCL",
  "showUrl": "https://open.spotify.com/show/2MAi0BvDc6GTFvKFPXnkCL",
  "releaseDate": "2026-03-23T16:29:00Z",
  "durationMs": 9104576,
  "durationSeconds": 9105,
  "explicit": false,
  "mediaTypes": ["AUDIO", "VIDEO"],
  "query": "artificial intelligence",
  "position": 1
}
```

Long descriptions and artwork fields are omitted from this README example for readability but remain available in dataset rows.

### How much does it cost to search Spotify podcasts and episodes?

Pricing uses one **Start** event per run plus one **Search result** event for every row saved.
There is no separate surcharge for episode metadata.

Current BRONZE-tier prices are:

- Start: **$0.00005 per run**
- Search result: **$0.0024 per row**

Example charge calculations:

| Saved results | Events charged |
| ---: | --- |
| 20 | 1 Start + 20 Search result events |
| 100 | 1 Start + 100 Search result events |
| 500 | 1 Start + 500 Search result events |

Your exact tier price is displayed by Apify before the run.
Platform compute is included under the Actor's PPE pricing model.

### Schedule recurring podcast research

Use an Apify Schedule to run the same query daily, weekly, or monthly.
Each dataset row includes `query`, `position`, and `scrapedAt`, making it suitable for snapshots.

For change tracking:

1. create a Task with stable input;
2. attach it to a Schedule;
3. send completed datasets to your database or webhook;
4. compare records by `uri` and runs by `scrapedAt`.

The Actor does not maintain historical state or send alerts itself.
Those workflows belong in your integration layer.

### Integration ideas

- Send rows to Google Sheets for editorial research.
- Load JSONL into a warehouse for topic coverage analysis.
- Trigger a webhook when a scheduled run finishes.
- Filter episode rows by `releaseDate` downstream.
- Join show IDs with separately collected public chart snapshots.
- Build a manual sponsorship qualification queue from publisher and show links.

Search position is contextual and may change between runs.
Treat it as an observation, not a permanent rank.

### Run with the Apify API

Replace `YOUR_TOKEN` with an Apify API token.

#### cURL

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~spotify-podcast-episode-search/run-sync-get-dataset-items?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"queries":["climate change"],"mode":"both","maxItems":20}'
```

#### JavaScript

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/spotify-podcast-episode-search').call({
  queries: ['climate change'],
  mode: 'both',
  maxItems: 20,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

#### Python

```python
from apify_client import ApifyClient
import os

client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('automation-lab/spotify-podcast-episode-search').call(run_input={
    'queries': ['climate change'],
    'mode': 'both',
    'maxItems': 20,
})
items = client.dataset(run['defaultDatasetId']).list_items().items
print(items)
```

### Use with Apify MCP

Add the Actor to Claude Code:

```bash
claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/spotify-podcast-episode-search"
```

#### Claude Desktop, Cursor, and VS Code

Claude Desktop, Cursor, and VS Code clients can use this HTTP MCP configuration:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/spotify-podcast-episode-search"
    }
  }
}
```

Example prompts:

- “Search Spotify for 20 podcasts and episodes about AI regulation.”
- “Export 50 Spotify episodes about renewable energy and summarize the publishers represented.”
- “Run my saved Spotify podcast research Task and return the dataset URL.”

### Reliability and retries

Spotify search requires a short anonymous browser session bootstrap.
After bootstrap, bounded pagination requests use the same coherent session.

The Actor retries temporary HTTP 429 and server errors with backoff.
It does not blindly retry malformed inputs, non-Spotify URLs, invalid response formats, or GraphQL errors.

If Spotify changes its search operation, the run fails with a diagnostic message rather than succeeding with misleading empty output.
Retry once later for a temporary upstream issue; inspect the run log if the error persists.

### Limits and data freshness

- Results reflect Spotify search at run time.
- Spotify decides catalog availability, ordering, locale behavior, and metadata completeness.
- Search may surface fewer records than requested.
- A result description can be long and may contain links supplied by its publisher.
- The Actor does not download audio, video, transcripts, or private listener data.
- The Actor does not guarantee exhaustive coverage of Spotify's catalog.
- Maximum output is 1,000 unique rows per run.
- Direct show and episode detail URLs are not inputs; use search terms or supported search URLs.

### Responsible use and legality

This Actor accesses public metadata surfaced by Spotify search.
You are responsible for complying with Spotify's terms, Apify's terms, and applicable laws.

Do not use exported contact or publisher information for unlawful spam, harassment, discrimination, or privacy-invasive profiling.
Respect intellectual property in episode names, descriptions, and artwork.
Store only the data you need and apply appropriate retention and access controls.

This documentation is not legal advice.

### Troubleshooting

#### Why did the run return fewer rows than `maxItems`?

Spotify may expose fewer records for a narrow query, or duplicate records may appear across searches and be removed by URI.
Try a broader phrase or additional distinct queries.

#### Why is a field `null`?

Spotify returns different fields for shows and episodes.
For example, show search rows normally have no episode release date or duration.

#### Why was my Spotify URL rejected?

Only public search URLs ending in `/podcasts` or `/episodes` are accepted.
Use a keyword in `queries` for all other search jobs.

#### Should I enable a proxy?

No proxy option is exposed.
The current direct anonymous browser route is the tested path and avoids unnecessary proxy cost.

#### Can I scrape an entire show's episode archive?

Not with this Actor.
It searches episodes by keyword rather than crawling every episode from a known show.

### Related Automation Lab Actors

- [Spotify Podcast Charts Scraper](https://apify.com/automation-lab/spotify-podcast-charts-scraper) exports ranked podcasts by market and genre.
- [Spotify Songs Scraper](https://apify.com/automation-lab/spotify-songs-scraper) extracts public metadata from known Spotify music URLs.

Use this Actor when the starting point is a podcast or episode keyword.
Use the charts Actor when the starting point is a country, chart, or genre ranking.

### FAQ

#### Does it need Spotify credentials?

No.
It uses the anonymous public web search session created for the run.

#### Can it return podcasts and episodes together?

Yes.
Set `mode` to `both`.

#### Are duplicates removed?

Yes.
The Actor deduplicates by canonical Spotify URI across all jobs in a run.

#### Can I export CSV or Excel?

Yes.
Use the dataset export controls or Apify dataset API.

#### Does it track changes automatically?

No.
Run a saved Task on a Schedule and compare datasets in your destination system.

#### Does it download media?

No.
It exports public metadata and links only.

# Actor input Schema

## `queries` (type: `array`):

Keywords or topics to search, such as artificial intelligence or climate change.

## `searchUrls` (type: `array`):

Optional public Spotify podcast or episode search URLs. Each URL must end in /podcasts or /episodes.

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

Return podcast shows, episodes, or both for query inputs. A search URL's own type always applies.

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

Maximum unique records saved across all searches.

## Actor input object example

```json
{
  "queries": [
    "artificial intelligence"
  ],
  "mode": "both",
  "maxItems": 20
}
```

# Actor output Schema

## `dataset` (type: `string`):

Podcast and episode records from all requested searches.

## `overview` (type: `string`):

Table view of the most useful podcast and episode fields.

# 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 = {
    "queries": [
        "artificial intelligence"
    ],
    "mode": "both",
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/spotify-podcast-episode-search").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 = {
    "queries": ["artificial intelligence"],
    "mode": "both",
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/spotify-podcast-episode-search").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "queries": [
    "artificial intelligence"
  ],
  "mode": "both",
  "maxItems": 20
}' |
apify call automation-lab/spotify-podcast-episode-search --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=automation-lab/spotify-podcast-episode-search",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/DzVhjLtpTex0JYNn1/builds/6HnmgAORmvQ2XInkC/openapi.json