{
  "openapi": "3.0.1",
  "info": {
    "title": "Podcast Search, Episodes & Charts API",
    "description": "Scrape podcasts as data. One row per episode: title, show notes, audio URL, duration, episode number, publish date, GUID. Plus one row per show — feed URL, categories, artwork, owner email — Apple's Top Shows charts by country, and keyword search. No API key, no login.",
    "version": "0.1",
    "x-build-id": "ocAugahUMJ7AWdGji"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/insight.solutions~podcast-api/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-insight.solutions-podcast-api",
        "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/insight.solutions~podcast-api/runs": {
      "post": {
        "operationId": "runs-sync-insight.solutions-podcast-api",
        "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/insight.solutions~podcast-api/run-sync": {
      "post": {
        "operationId": "run-sync-insight.solutions-podcast-api",
        "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": {
          "podcasts": {
            "title": "Podcasts",
            "type": "array",
            "description": "One entry per show. Four shapes work: an **Apple Podcasts link** (`https://podcasts.apple.com/us/podcast/huberman-lab/id1545953110` — an episode link works too, it resolves to the show), a **bare Apple ID** (`1545953110`), an **RSS feed URL** (`https://feeds.megaphone.fm/hubermanlab`, `https://lexfridman.com/feed/podcast/` — it does not have to end in .xml), or a **show name** (`Huberman Lab`), which is resolved through Apple's search and flagged as `resolvedFrom: search` on the row. A number shorter than five digits is read as a name, because `1619` is a podcast. To be explicit, prefix an entry: `feed:`, `id:` or `name:`. Duplicates are read, and billed, once.",
            "items": {
              "type": "string"
            }
          },
          "maxEpisodesPerPodcast": {
            "title": "Episodes per podcast",
            "minimum": 0,
            "maximum": 100000,
            "type": "integer",
            "description": "How many episodes to return for each show, newest first. Set **0 for every episode in the feed** — that is the whole back catalogue, which for a daily news show is a few thousand rows. The feed is one request whatever you ask for, so a high number costs no extra requests, only rows. With `episodeSource: apple` the ceiling is 200: Apple's lookup will not serve more than that, however many the show has.",
            "default": 50
          },
          "episodeSource": {
            "title": "Where episodes come from",
            "enum": [
              "rss",
              "apple"
            ],
            "type": "string",
            "description": "**RSS** is the show's own feed: full show notes, the real audio URL, the publisher's GUID, duration, episode and season numbers, per-episode artwork — and no 200-episode ceiling. **Apple** is the iTunes lookup: fewer fields, descriptions already flattened to plain text, no episode numbers, capped at 200 — but it works for a show whose feed is unreachable, and it is one request instead of a multi-megabyte download. RSS is the default and the fallback happens automatically: if the feed will not answer, Apple's episode list is used instead and a free diagnostic row says so.",
            "default": "rss"
          },
          "includeDescriptionHtml": {
            "title": "Keep the HTML of descriptions",
            "type": "boolean",
            "description": "Add a `descriptionHtml` column holding the show notes as the publisher wrote them, links and all. The plain-text `description` column is always there; this is for when you want the anchor tags — sponsor links, chapter links, guest bios. It makes rows several times larger and it is off by default.",
            "default": false
          },
          "includeRating": {
            "title": "Include the star rating",
            "type": "boolean",
            "description": "Add `rating` and `ratingCount` to each podcast row. Apple publishes a podcast's star rating **only on the show's web page**, so this costs one extra request per show — and that page is around 600 KB of HTML for two numbers. Off by default; the two columns are null unless you turn it on. It never fails a run: a page that will not load costs the rating, not the episodes.",
            "default": false
          },
          "searchQueries": {
            "title": "Search queries",
            "type": "array",
            "description": "Find shows by keyword. Each query returns up to `maxResultsPerQuery` **podcast** rows — title, author, feed URL, genres, artwork, Apple's episode count — and no episodes unless you turn on `includeEpisodesForSearchHits`. This is the input for building a list: \"every true-crime podcast Apple knows about\", \"shows whose name mentions Bitcoin\".",
            "items": {
              "type": "string"
            }
          },
          "maxResultsPerQuery": {
            "title": "Results per query",
            "minimum": 1,
            "maximum": 200,
            "type": "integer",
            "description": "How many shows each search query returns. Apple's own ceiling is 200 and asking for more does not get more.",
            "default": 25
          },
          "genreId": {
            "title": "Genre filter (Apple genre ID)",
            "type": "string",
            "description": "Restrict every search query to one Apple podcast genre, by numeric ID — `1462` History, `1488` True Crime, `1489` News, `1533` Science, `1512` Health & Fitness, `1318` Technology. Leave empty to search all genres. It has no effect on the `podcasts` or `charts` inputs."
          },
          "includeEpisodesForSearchHits": {
            "title": "Also fetch episodes for search hits",
            "type": "boolean",
            "description": "Read every search hit's RSS feed as well, returning `maxEpisodesPerPodcast` episodes for each. This turns one query into one request per hit plus a feed download each, so a 25-result query becomes 26 requests and a lot of rows. Off by default. Shows that Apple lists with no public feed — Apple-exclusive ones, mostly — get a free diagnostic row instead.",
            "default": false
          },
          "charts": {
            "title": "Country charts",
            "type": "array",
            "description": "Two-letter country codes. Each one returns Apple's current **Top Shows** chart for that country as ranked `chart` rows: rank, show, artist, genres, artwork and the Apple link. This is the cheapest data here — one request buys up to 100 rows — and it is how you watch a market rather than a show.",
            "items": {
              "type": "string"
            }
          },
          "chartSize": {
            "title": "Chart size",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "How deep each chart goes. Apple serves exactly three sizes — 25, 50 and 100 — and anything else is rounded to the nearest of them, because any other number is a 404.",
            "default": 50
          },
          "includeChartDetails": {
            "title": "Enrich chart rows",
            "type": "boolean",
            "description": "Look each charting show up, adding its feed URL, episode count, latest episode date and explicit flag to the chart row. It is **one extra request per show**, so an enriched Top 100 is 101 requests and takes a couple of minutes. Off by default: the chart itself already carries the rank, the name, the artist, the genres and the artwork.",
            "default": false
          },
          "country": {
            "title": "Country (storefront)",
            "type": "string",
            "description": "Two-letter ISO country code, lower case. Apple's catalogue is per-country: a show published only in Germany is not in the `us` storefront at all, search rankings differ, and so do the charts. RSS feeds are global — the feed is the same wherever you read it from — so this changes what Apple tells you, not what the publisher does.",
            "default": "us"
          },
          "maxConcurrency": {
            "title": "Shows in parallel",
            "minimum": 1,
            "maximum": 10,
            "type": "integer",
            "description": "How many shows, queries or charts are read at once. Each parallel worker keeps its own proxy session, so one blocked feed burns only its own exit IP. Feeds are large — a long-running show is several megabytes — so raising this raises memory as well as speed.",
            "default": 3
          },
          "maxRunSecs": {
            "title": "Maximum run time (seconds)",
            "minimum": 30,
            "maximum": 3600,
            "type": "integer",
            "description": "Wall-clock budget for the whole run. When it is reached the Actor stops fetching, keeps and bills for every row it already wrote, and files a free diagnostic row for each entry it never reached. A show stopped part-way keeps its rows. Nothing is charged for work that did not happen.",
            "default": 240
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Apple's endpoints and the big podcast hosts answer datacenter addresses happily, so the default is Apify's datacenter proxy — much cheaper than residential, and the proxy cost is already inside the per-row price. Switch to residential only if you are reading a feed from a host that rate-limits shared addresses. Sessions rotate automatically when an exit IP is refused.",
            "default": {
              "useApifyProxy": true
            }
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}