Listen Notes

Request to delete a podcast. THIS ACTS ON THE PUBLIC LISTEN NOTES DIRECTORY, NOT ON ANYTHING THIS ACCOUNT OWNS: it asks Listen Notes to remove a podcast from the directory every Listen Notes user searches. It is a REQUEST, not an immediate deletion -- Listen Notes reviews it within 12 hours and the response's `status` is "in review" (or "deleted" if the podcast was already gone). It is intended for podcast HOSTING SERVICES acting on behalf of the podcaster who owns the feed; do not call it for a podcast the user does not control. THE VENDOR DOCUMENTS A NO-OP: passing reason="testing" tells Listen Notes you are testing the endpoint and "we will not actually delete the podcast" -- use it for any call that is not a genuine deletion request. Measured 2026-09-17: reason=testing -> 200 {"status": "in review"}. DELETE /api/v2/podcasts/{id}. Podcast hosting services can use this endpoint to streamline the process of podcast deletion on behave of their users (podcasters). We will review the deletion request within 12 hours. If the podcast is already deleted, the "status" field in the response will be "deleted". Otherwise, the status field will be "in review". If you want to get a notification once the podcast is deleted, you can configure a webhook url in the dashboard: listennotes.com/api/dashboard/#webhooks

Fetch a list of best podcasts by genre. GET /api/v2/best_podcasts. Get a list of curated best podcasts by genre, which are curated by Listen Notes staffs based on various signals from the Internet, e.g., top charts on other podcast platforms, recommendations from mainstream media, user activities on listennotes.com... You can get the genre ids from GET /genres endpoint. This endpoint returns same data as https://www.listennotes.com/best-podcasts/

Fetch curated lists of podcasts. GET /api/v2/curated_podcasts. A bunch of curated lists from online media. For each list, you'll get basic info of up to 5 podcasts. To get detailed meta data of all podcasts in a specific list, you need to use GET /curated_podcasts/{id}. We add new curated lists to the database on a daily basis.

Fetch a curated list of podcasts by id. GET /api/v2/curated_podcasts/{id}. Get detailed meta data of all podcasts in a specific curated list. This endpoint returns same data as https://www.listennotes.com/curated-podcasts/

Fetch detailed meta data for an episode by id. GET /api/v2/episodes/{id}. Fetch detailed meta data for a specific episode.

Fetch recommendations for an episode. GET /api/v2/episodes/{id}/recommendations. Fetch up to 8 episode recommendations based on the given episode id.

Fetch a list of podcast genres. GET /api/v2/genres. Get a list of podcast genres that are supported in Listen Notes. The genre id can be passed to other endpoints as a parameter to get podcasts in a specific genre, e.g., GET /best_podcasts, GET /search... You may want to cache the list of genres on the client side.

Fetch a random podcast episode. GET /api/v2/just_listen. Recently published episodes are more likely to be fetched. Good luck!

Fetch a list of supported languages for podcasts. GET /api/v2/languages. Get a list of languages that are supported in Listen Notes database. You can use the language string as query parameter in GET /search.

Fetch a list of your playlists. GET /api/v2/playlists. This endpoint returns same data as listennotes.com/listen under your account. You can use the page parameter to do pagination and fetch more playlists.

Fetch a playlist's info and items (i.e., episodes or podcasts). GET /api/v2/playlists/{id}. A playlist can be an episode list (i.e., all items are episodes) or a podcast list (i.e., all items are podcasts), which is essentially the same as those created via listennotes.com/listen/. This endpoint fetches a list of items (i.e., episodes or podcasts) in the playlist. You can use the last_pub_date_ms parameter to do pagination and fetch more items. A playlist can be public (discoverable on ListenNotes.com), unlisted (accessible to anyone who knows the playlist id), or private (accessible to its owner). You can fetch all playlists created by you, and public / unlisted playlists created by others.

Fetch detailed meta data and episodes for a podcast by id. GET /api/v2/podcasts/{id}. Fetch detailed meta data and episodes for a specific podcast (up to 10 episodes each time). You can use the next_episode_pub_date parameter to do pagination and fetch more episodes. During pagination with next_episode_pub_date, an empty episodes array in the response signals that no more episodes are available.

Fetch audience demographics for a podcast. GET /api/v2/podcasts/{id}/audience. Fetch audience demographics for a podcast - 1) directly measured on the Listen Notes platform; 2) only supports audience breakdown by regions for now; 3) not every podcast has data.

Fetch recommendations for a podcast. GET /api/v2/podcasts/{id}/recommendations. Fetch up to 8 podcast recommendations based on the given podcast id.

Fetch podcasts by a publisher's domain name. GET /api/v2/podcasts/domains/{domain_name}. Fetch podcasts by a publisher's domain name, e.g., nytimes.com, wondery.com, npr.org... Each request will return up to 10 podcasts. You can use the page parameter to paginate.

Fetch a list of supported countries/regions for best podcasts. GET /api/v2/regions. It returns a dictionary of country codes (e.g., us, gb...) & country names (United States, United Kingdom...). The country code is used in the query parameter region of GET /best_podcasts.

Fetch related search terms. PRO/ENTERPRISE ONLY. Measured 2026-09-17 with a valid FREE-plan key: 401 {"error": "Please upgrade to PRO or ENTERPRISE plan to use this endpoint. Learn more: listennotes.com/api/pricing"}. That 401 is about the PLAN, not the key -- the same key works on every other tool here. Do not treat it as a credential failure and do not retry it; the account needs an upgrade at listennotes.com/api/pricing. GET /api/v2/related_searches. Suggest related search terms. The results are more comprehensive than from GET /typeahead. This endpoint is available only in the PRO/ENTERPRISE plan.

Full-text search. GET /api/v2/search. Full-text search on episodes, podcasts, or curated lists of podcasts. Use the offset parameter to paginate through search results. The FREE plan allows to see up to 30 search results (or offset < 30) per query. The PRO plan allows to see up to 300 search results (or offset < 300) per query. The ENTERPRISE plan allows to see up to 10,000 search results (or offset < 10000) per query.

Find individual episodes by searching for their titles. GET /api/v2/search_episode_titles. Conduct targeted searches for individual episodes by title and refine results using the podcast id such as Listen Notes Podcast ID, Apple Podcasts ID, Spotify ID, or RSS feed URL. This endpoint is specially designed to streamline the import of specific episodes from platforms like Apple Podcasts and Spotify into your application. Compared to the GET /search endpoint, which performs full-text searches across multiple fields, this endpoint focuses solely on episode titles for enhanced accuracy and performance.

Spell check on a search term. PRO/ENTERPRISE ONLY. Measured 2026-09-17 with a valid FREE-plan key: 401 {"error": "Please upgrade to PRO or ENTERPRISE plan to use this endpoint. Learn more: listennotes.com/api/pricing"}. That 401 is about the PLAN, not the key -- the same key works on every other tool here. Do not treat it as a credential failure and do not retry it; the account needs an upgrade at listennotes.com/api/pricing. GET /api/v2/spellcheck. Suggest a list of words that correct the spelling errors of a search term. This endpoint is available only in the PRO/ENTERPRISE plan.

Fetch trending search terms. GET /api/v2/trending_searches. Fetch up to 10 most recent trending search terms on the Listen Notes platform.

Typeahead search. GET /api/v2/typeahead. Suggest search terms, podcast genres, and podcasts.

Batch fetch basic meta data for episodes. PRO/ENTERPRISE ONLY -- the vendor's own description says so, and it is measured: 2026-09-17, a valid FREE-plan key answered 401 {"error": "Please upgrade to PRO or ENTERPRISE plan to use this endpoint. Learn more: listennotes.com/api/pricing"}. That 401 is about the PLAN, not the key. On a FREE plan, fetch episodes one at a time with Fetch detailed meta data for an episode by id instead. POST /api/v2/episodes. Batch fetch basic meta data for up to 10 episodes. This endpoint could be used to implement custom playlists for individual episodes. For detailed meta data of an individual episode, you need to use GET /episodes/{id}. This endpoint is available only in the PRO/ENTERPRISE plan.

Batch fetch basic meta data for podcasts. PRO/ENTERPRISE ONLY -- the vendor's own description says so, and it is measured: 2026-09-17, a valid FREE-plan key answered 401 {"error": "Please upgrade to PRO or ENTERPRISE plan to use this endpoint. Learn more: listennotes.com/api/pricing"}. That 401 is about the PLAN, not the key. On a FREE plan, fetch podcasts one at a time with Fetch detailed meta data and episodes for a podcast by id instead. POST /api/v2/podcasts. Batch fetch basic meta data for up to 10 podcasts. This endpoint could be used to build something like OPML import, allowing users to import a bunch of podcasts via rss urls. For detailed meta data (including episodes) of an individual podcast, you need to use GET /podcasts/{id}. This endpoint is available only in the PRO/ENTERPRISE plan.

Refresh RSS feed of a podcast. PRO/ENTERPRISE ONLY -- the vendor's own description says so, and it is measured: 2026-09-17, a valid FREE-plan key answered 401 {"error": "Please upgrade to PRO or ENTERPRISE plan to use this endpoint. Learn more: listennotes.com/api/pricing"}. That 401 is about the PLAN, not the key. POST /api/v2/podcasts/{id}/rss. Refresh a podcast's RSS feed. Each podcast is limited to one refresh per hour. Refresh durations range from a few seconds to several minutes, contingent on the RSS feed size and server responsiveness. This endpoint is available only in the PRO/ENTERPRISE plan.

Submit a podcast to Listen Notes database. THIS WRITES TO THE PUBLIC LISTEN NOTES DIRECTORY, NOT TO ANYTHING THIS ACCOUNT OWNS: it submits an RSS feed for inclusion in the directory every Listen Notes user searches. If the feed is already indexed the response's `status` is "found" and nothing is created; otherwise it is "in review" (Listen Notes reviews within 12 hours) or "rejected". Intended for podcast hosting services submitting on behalf of their users. Measured 2026-09-17 with an already-indexed feed -> 200 {"status": "found"}. POST /api/v2/podcasts/submit. Podcast hosting services can use this endpoint to help your users directly submit a new podcast to Listen Notes database. If the podcast doesn't exist in the database, "status" in the response will be "in review", and we'll review it within 12 hours. If the podcast exists, "status" in the response will be "found". If this submission is rejected, "status" in the response will be "rejected". You can use POST /podcasts to check if multiple podcasts exist in the database. If you want to get a notification once the podcast is accepted, you can either specify the "email" parameter or configure a webhook url in the dashboard: listennotes.com/api/dashboard/#webhooks