# Spotify Podcast Charts Scraper (`automation-lab/spotify-podcast-charts-scraper`) Actor

Export current Spotify podcast chart rankings by market and genre with rank movement, publisher, artwork, descriptions, and Spotify links.

- **URL**: https://apify.com/automation-lab/spotify-podcast-charts-scraper.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** Social media
- **Stats:** 3 total users, 2 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.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md).

If your project is in a different language, use 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 Charts Scraper

Export Spotify's current public podcast rankings by country and chart as clean JSON.

Collect Top Podcasts, Trending Podcasts, and supported genre charts without a Spotify login, API key, browser, or proxy.
Each dataset row is one ranked show with its rank, movement, publisher, description, artwork, Spotify identifiers, market, chart, and observation time.

### What this Actor does

Spotify Podcast Charts Scraper turns the public charts on `podcastcharts.byspotify.com` into integration-ready records.

It can:

- collect one or many Spotify markets in one run;
- export Top Podcasts and Trending Podcasts in 26 supported markets;
- export 17 genre charts in the seven markets where Spotify offers them;
- limit results independently for every market/chart pair;
- preserve chart order as a one-based rank;
- expose Spotify's rank-movement label;
- add the original source object when auditability is useful;
- run efficiently over anonymous JSON instead of a browser.

Use scheduled Apify runs to build daily or weekly rank history.
The Actor returns a current snapshot; it does not invent historical ranks that Spotify does not expose.

### Who is it for

**Podcast networks** monitor titles across markets and genres.

**Talent scouts** identify rising shows from Trending Podcasts.

**Sponsorship teams** build prospect lists from ranked podcasts and publishers.

**Agencies** automate recurring client rank reports.

**Creators** compare their category position with competitors.

**Media researchers** create reproducible snapshots for market analysis.

**Data teams** feed rankings into warehouses, dashboards, alerts, and notebooks.

### Why use this Actor

- **Focused workflow:** podcast rankings rather than general Spotify entity scraping.
- **Current market matrix:** invalid genre/region combinations fail clearly instead of silently yielding no data.
- **Typed output:** stable fields are ready for datasets and integrations.
- **Low overhead:** direct HTTP requests, 256 MB memory, and no image downloads.
- **Repeatable snapshots:** every row includes `observedAt`, `region`, and `chart`.
- **Defensive extraction:** bounded retries, content-type checks, payload-shape checks, and row validation.

### Supported markets

Top Podcasts and Trending Podcasts are supported in:

`us`, `ar`, `au`, `at`, `br`, `ca`, `cl`, `co`, `dk`, `fi`, `fr`, `de`, `in`, `id`, `ie`, `it`, `jp`, `mx`, `nz`, `no`, `ph`, `pl`, `es`, `se`, `nl`, and `gb`.

Genre charts are currently available only in:

`us`, `au`, `br`, `de`, `mx`, `se`, and `gb`.

Spotify can change this public catalog.
The Actor validates against the catalog verified for this release.

### Supported charts

Universal charts:

- `top-podcasts`
- `trending`

Genre charts:

- `arts`
- `business`
- `comedy`
- `education`
- `fiction`
- `health-fitness`
- `history`
- `leisure`
- `music`
- `news`
- `religion-spirituality`
- `science`
- `society-culture`
- `sports`
- `technology`
- `true-crime`
- `tv-film`

### Quick start

1. Open the Actor input.
2. Select one or more **Regions**.
3. Select one or more **Charts**.
4. Set **Maximum shows per chart**.
5. Leave raw data disabled unless you need the source object.
6. Click **Start**.
7. Open **Dataset → Podcast rankings** when the run succeeds.
8. Export JSON, CSV, Excel, XML, or RSS from Apify.

A safe first run is:

```json
{
  "regions": ["us"],
  "charts": ["top-podcasts", "trending"],
  "maxItemsPerChart": 20,
  "includeRawData": false
}
````

### Input parameters

| Field | Type | Default | Description |
|---|---:|---:|---|
| `regions` | string\[] | `["us"]` | Spotify two-letter market codes to collect. |
| `charts` | string\[] | `["top-podcasts"]` | Ranking lists to collect in every selected region. |
| `maxItemsPerChart` | integer | `100` | Maximum rows per region/chart pair, from 1 to 200. |
| `includeRawData` | boolean | `false` | Include Spotify's original chart object as `rawData`. |

The Actor removes duplicate region and chart values.
Input values are normalized to lowercase.
Unsupported values fail before any request is made.
A genre chart paired with an unsupported market also fails before collection.

### Output fields

| Field | Type | Meaning |
|---|---|---|
| `rank` | integer | One-based position in this chart snapshot. |
| `showUri` | string | Spotify URI, such as `spotify:show:...`. |
| `showId` | string | ID extracted from the Spotify URI. |
| `showUrl` | string | Public Spotify show URL. |
| `showName` | string | Podcast title. |
| `publisher` | string or null | Publisher/creator supplied by Spotify. |
| `description` | string or null | Current Spotify show description. |
| `artworkUrl` | string or null | Spotify artwork URL; the image is not downloaded. |
| `chartRankMove` | string or null | Usually `UP`, `DOWN`, or `UNCHANGED`. |
| `region` | string | Requested Spotify market code. |
| `chart` | string | Requested chart identifier. |
| `observedAt` | ISO timestamp | UTC observation time shared by this run. |
| `sourceUrl` | string | Corresponding public Spotify chart page. |
| `rawData` | object, optional | Original source row when enabled. |

### Example output

```json
{
  "rank": 1,
  "showUri": "spotify:show:4rOoJ6Egrf8K2IrywzwOMk",
  "showId": "4rOoJ6Egrf8K2IrywzwOMk",
  "showUrl": "https://open.spotify.com/show/4rOoJ6Egrf8K2IrywzwOMk",
  "showName": "The Joe Rogan Experience",
  "publisher": "Joe Rogan",
  "description": "The official podcast of comedian Joe Rogan.",
  "artworkUrl": "https://i.scdn.co/image/ab67656300005f1f2e7936ee02774abeceb710f2",
  "chartRankMove": "UNCHANGED",
  "region": "us",
  "chart": "top-podcasts",
  "observedAt": "2026-07-25T03:50:35.053Z",
  "sourceUrl": "https://podcastcharts.byspotify.com/us/top-podcasts"
}
```

This example came from current public output during local validation.
Rankings and descriptions naturally change over time.

### Limits and data behavior

Spotify currently returns up to 200 rows for Top Podcasts and Trending Podcasts.
Genre charts currently return up to 50 rows.
`maxItemsPerChart` is a local output limit because Spotify may ignore the API `limit` parameter.

The maximum applies to every selected pair.
For example, two regions × three charts × 20 items can produce up to 120 rows.
Naturally shorter charts produce fewer rows.

The Actor does not fetch episodes, reviews, audio, listening counts, or private audience analytics.
It does not resolve a show's historical rank.
Schedule runs and retain datasets if you need history.

### Pricing

This Actor uses pay-per-event pricing:

- **$0.001 per run started**;
- **$0.00001 per dataset item** on every Apify plan.

The Apify Console displays the active event prices before a run.
Set a maximum total charge in Apify when you need a hard budget cap.
Final cost depends mainly on the number of selected region/chart pairs and the rows each chart contains.

Example Actor charges:

- US Top Podcasts capped at 20: $0.001 + up to $0.0002 = **up to $0.0012**;
- US Top + Trending capped at 100: $0.001 + up to $0.002 = **up to $0.003**;
- three markets and two genre charts capped at 50: $0.001 + up to $0.003 = **up to $0.004**.

These are Actor event charges and exclude any separate post-run storage operations billed by Apify.

### Build a rank history

Create a daily or weekly schedule with fixed input.
Store each run's dataset or merge rows into your warehouse.
Use `(observedAt, region, chart, showUri)` as a snapshot key.
Compare `rank` between snapshots for numeric movement.
Spotify's `chartRankMove` is the source label, not a numeric delta.

A monitoring workflow can:

1. run every morning;
2. export rows to BigQuery, Snowflake, Sheets, or S3;
3. compare each show with its prior snapshot;
4. alert when a show enters the top 20;
5. publish a dashboard by market and genre.

### Sponsorship and talent discovery

Use Trending Podcasts to find newly visible shows.
Join `showUri` or `showId` across snapshots to measure persistence.
Group by `publisher` to find networks with several ranked titles.
Use descriptions for classification, while reviewing results manually before outreach.

Chart rank is not the same as downloads, revenue, reach, or audience demographics.
Do not present it as those metrics.

### API usage with cURL

Start a run and wait for its dataset:

```bash
curl "https://api.apify.com/v2/acts/automation-lab~spotify-podcast-charts-scraper/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"regions":["us"],"charts":["top-podcasts"],"maxItemsPerChart":20}'
```

Keep tokens in environment variables or a secret manager.
Do not commit them to source control.

### JavaScript API example

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/spotify-podcast-charts-scraper').call({
  regions: ['us', 'gb'],
  charts: ['trending'],
  maxItemsPerChart: 50,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

Install the client with `npm install apify-client`.

### Python API example

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('automation-lab/spotify-podcast-charts-scraper').call(run_input={
    'regions': ['us', 'gb', 'au'],
    'charts': ['comedy'],
    'maxItemsPerChart': 50,
})
items = client.dataset(run['defaultDatasetId']).list_items().items
print(items)
```

Install the client with `pip install apify-client`.

### Webhooks and integrations

Attach an Apify webhook to `ACTOR.RUN.SUCCEEDED` to trigger your pipeline.
Common destinations include Make, Zapier, Slack, Google Sheets, Airbyte, Keboola, and custom HTTP services.

For production workflows:

- pin your input in an Apify Task;
- schedule the Task rather than duplicating input;
- store the run ID with each imported batch;
- alert on failed runs;
- deduplicate on region, chart, show URI, and observation time.

### MCP setup

Use the Apify MCP server to run this Actor from an AI client.

Claude Code:

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

Claude Desktop, Cursor, and VS Code MCP configuration:

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

Example prompts:

- "Run Spotify Podcast Charts Scraper for the US top-podcasts chart and return 20 shows."
- "Collect comedy podcast charts in the US, UK, and Australia, then compare publishers."
- "Fetch US Trending Podcasts and summarize shows that would fit a technology sponsor."

Review generated interpretations against the original dataset.

### Troubleshooting

#### Why did the run reject my region/chart combination?

Spotify offers genre charts only in US, AU, BR, DE, MX, SE, and GB.
Use `top-podcasts` or `trending` for other supported regions.

#### Why did I receive fewer rows than requested?

The source chart may contain fewer entries.
Genre charts currently expose up to 50 rows.
The Actor never duplicates rows to fill a requested limit.

#### Why did a run fail after retries?

Spotify may be temporarily unavailable, rate limiting, or changing its response.
Inspect the run log for the affected region and chart, then retry later.
Persistent shape errors require an Actor update rather than repeated runs.

#### Why is `rawData` missing?

Set `includeRawData` to `true`.
Normalized fields remain the recommended stable integration contract.

### Legality and responsible use

This Actor accesses public chart data without authentication.
You are responsible for complying with Spotify's terms, Apify's terms, and applicable law.
Use reasonable schedules and avoid unnecessary repeated collection.

Podcast descriptions and publisher names can contain personal or copyrighted material.
Store and process them only for a lawful purpose.
Do not use chart position alone for automated high-impact decisions.
Do not imply endorsement by Spotify or by any listed podcast.

This Actor is an independent automation tool and is not affiliated with Spotify.

### Related Automation Lab Actors

- [Spotify Scraper](https://apify.com/automation-lab/spotify-scraper) — broader Spotify entity and metadata workflows.
- [Podcast Scraper](https://apify.com/automation-lab/podcast-scraper) — Apple Podcasts search, show metadata, and episodes.
- [Spotify Public Weekly Charts Scraper](https://apify.com/automation-lab/spotify-public-weekly-charts-scraper) — current weekly songs, albums, and artists rankings.

Choose this Actor when the primary entity is a **podcast chart position**.
Choose the related Actors when you need broader metadata, episode discovery, or music charts.

### FAQ

#### Does it need my Spotify account?

No.
The current public chart JSON is anonymous.

#### Does it use a browser or proxy?

No.
The Actor uses direct HTTP requests and does not download artwork files.

#### Are rankings real time?

They are current at the time Spotify serves the chart, but Spotify controls refresh timing.
`observedAt` records when the Actor fetched the data, not when Spotify recalculated it.

#### Can I collect every market and category?

Yes for valid combinations, but genre charts are limited to seven markets.
Large matrix runs create one request per market/chart pair and more item charges.

#### Can I get historical rankings?

The source provides a current snapshot.
Schedule the Actor and retain results to create your own history.

#### Can I use the data commercially?

Public availability does not automatically grant every use.
Assess your use case, applicable terms, and legal obligations.

#### What happens if Spotify changes the route?

The Actor validates response status, content type, and record shape and fails clearly rather than returning misleading empty success.
Report persistent failures with the run URL and non-secret input.

### Support

For a reproducible issue, include:

- the Apify run URL;
- the non-secret input;
- the region and chart that failed;
- the approximate failure time;
- the expected behavior.

Do not include your API token in support messages.

# Actor input Schema

## `regions` (type: `array`):

Spotify market codes to collect. Genre charts are available only in US, AU, BR, DE, MX, SE, and GB.

## `charts` (type: `array`):

Podcast ranking lists to collect. Top Podcasts and Trending work in every supported region; genre charts work only in US, AU, BR, DE, MX, SE, and GB.

## `maxItemsPerChart` (type: `integer`):

Maximum ranked shows saved for each region/chart pair. Spotify currently returns up to 200 for Top/Trending and 50 for genres.

## `includeRawData` (type: `boolean`):

Add the original Spotify chart object under rawData for audit and forward compatibility.

## Actor input object example

```json
{
  "regions": [
    "us"
  ],
  "charts": [
    "top-podcasts",
    "trending"
  ],
  "maxItemsPerChart": 20,
  "includeRawData": false
}
```

# Actor output Schema

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

Dataset API URL for ranked shows with publisher, rank movement, market, chart, Spotify URL, and observation time.

# 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 = {
    "regions": [
        "us"
    ],
    "charts": [
        "top-podcasts",
        "trending"
    ],
    "maxItemsPerChart": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/spotify-podcast-charts-scraper").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 = {
    "regions": ["us"],
    "charts": [
        "top-podcasts",
        "trending",
    ],
    "maxItemsPerChart": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/spotify-podcast-charts-scraper").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 '{
  "regions": [
    "us"
  ],
  "charts": [
    "top-podcasts",
    "trending"
  ],
  "maxItemsPerChart": 20
}' |
apify call automation-lab/spotify-podcast-charts-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Spotify Podcast Charts Scraper",
        "description": "Export current Spotify podcast chart rankings by market and genre with rank movement, publisher, artwork, descriptions, and Spotify links.",
        "version": "0.1",
        "x-build-id": "4MDt2JFYYRIrvhWip"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/automation-lab~spotify-podcast-charts-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-automation-lab-spotify-podcast-charts-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/automation-lab~spotify-podcast-charts-scraper/runs": {
            "post": {
                "operationId": "runs-sync-automation-lab-spotify-podcast-charts-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/automation-lab~spotify-podcast-charts-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-automation-lab-spotify-podcast-charts-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "properties": {
                    "regions": {
                        "title": "Regions",
                        "minItems": 1,
                        "uniqueItems": true,
                        "type": "array",
                        "description": "Spotify market codes to collect. Genre charts are available only in US, AU, BR, DE, MX, SE, and GB.",
                        "items": {
                            "type": "string",
                            "enum": [
                                "us",
                                "ar",
                                "au",
                                "at",
                                "br",
                                "ca",
                                "cl",
                                "co",
                                "dk",
                                "fi",
                                "fr",
                                "de",
                                "in",
                                "id",
                                "ie",
                                "it",
                                "jp",
                                "mx",
                                "nz",
                                "no",
                                "ph",
                                "pl",
                                "es",
                                "se",
                                "nl",
                                "gb"
                            ],
                            "enumTitles": [
                                "United States",
                                "Argentina",
                                "Australia",
                                "Austria",
                                "Brazil",
                                "Canada",
                                "Chile",
                                "Colombia",
                                "Denmark",
                                "Finland",
                                "France",
                                "Germany",
                                "India",
                                "Indonesia",
                                "Ireland",
                                "Italy",
                                "Japan",
                                "Mexico",
                                "New Zealand",
                                "Norway",
                                "Philippines",
                                "Poland",
                                "Spain",
                                "Sweden",
                                "Netherlands",
                                "United Kingdom"
                            ]
                        },
                        "default": [
                            "us"
                        ]
                    },
                    "charts": {
                        "title": "Charts",
                        "minItems": 1,
                        "uniqueItems": true,
                        "type": "array",
                        "description": "Podcast ranking lists to collect. Top Podcasts and Trending work in every supported region; genre charts work only in US, AU, BR, DE, MX, SE, and GB.",
                        "items": {
                            "type": "string",
                            "enum": [
                                "top-podcasts",
                                "trending",
                                "arts",
                                "business",
                                "comedy",
                                "education",
                                "fiction",
                                "health-fitness",
                                "history",
                                "leisure",
                                "music",
                                "news",
                                "religion-spirituality",
                                "science",
                                "society-culture",
                                "sports",
                                "technology",
                                "true-crime",
                                "tv-film"
                            ],
                            "enumTitles": [
                                "Top Podcasts",
                                "Trending Podcasts",
                                "Arts",
                                "Business",
                                "Comedy",
                                "Education",
                                "Fiction",
                                "Health & Fitness",
                                "History",
                                "Leisure",
                                "Music",
                                "News",
                                "Religion & Spirituality",
                                "Science",
                                "Society & Culture",
                                "Sports",
                                "Technology",
                                "True Crime",
                                "TV & Film"
                            ]
                        },
                        "default": [
                            "top-podcasts"
                        ]
                    },
                    "maxItemsPerChart": {
                        "title": "Maximum shows per chart",
                        "minimum": 1,
                        "maximum": 200,
                        "type": "integer",
                        "description": "Maximum ranked shows saved for each region/chart pair. Spotify currently returns up to 200 for Top/Trending and 50 for genres.",
                        "default": 100
                    },
                    "includeRawData": {
                        "title": "Include raw Spotify data",
                        "type": "boolean",
                        "description": "Add the original Spotify chart object under rawData for audit and forward compatibility.",
                        "default": false
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```
