Endpoints
2 endpoints return podcasts on Spotify.
Schema
Single-item endpoints return this object as data; list endpoints return an array of them as data with a page object. The standard meta comes with every response.
platformstringPlatform ID (spotify, youtube, …).
idstringPlatform-native show ID (string), the one in its page's URL.
urlstring uriCanonical show page URL.
titlestringThe show's name as the platform lists it.
descriptionstringnullableAbout the show, as plain text; null when it has none or the platform shows none.
publisher_namestringnullableWho publishes the show, as the platform names them; null when it does not.
publisherobjectnullableThe platform account of the publisher; null when the platform names them without an account (always on Spotify).
ShowHide 6 child fields
idstringnullablePlatform-native account ID; null when only the handle is known.
usernamestringnullableHandle without the @; null when the account has none.
display_namestringnullableDisplay name shown on the profile.
urlstring urinullableCanonical profile URL.
avatar_urlstring urinullableProfile picture URL. Platform CDN URLs can expire within hours.
is_verifiedbooleannullablePlatform verification badge; null where the platform has no badge.
cover_urlstring urinullableCover art URL at the largest size the platform serves; null when it has none. Platform CDN URLs can expire within hours.
media_typestringnullableWhat its episodes are: audio, video or mixed (both); null when the platform does not say. New values may be added.
One ofaudiovideomixed
show_typestringnullableepisodic: its episodes stand alone, newest first; serial: they are heard in order, from the first. Null when the platform does not say. New values may be added.
One ofepisodicserial
categoriesstring[]Categories or topics the platform files it under, as shown (not normalized), the main one first; [] when none (listed in unknown_fields when the source cannot see them).
is_explicitbooleannullableMarked as holding explicit content by the platform; null when it does not say.
ratingnumbernullableListeners' average rating, 1 to 5 stars (metrics.rating_count ratings behind it; listed in approximate_fields when the platform rounds it); null when unrated or the platform shows none.
latest_episode_atstring date-timenullableWhen its newest episode came out, RFC 3339 UTC; listed in approximate_fields when read from display text or a date alone. Null when the source does not show it.
metricsobjectCounts at fetch time; null = hidden or not exposed, 0 = zero.
ShowHide 2 child fields
episode_countintegernullableEpisodes the platform counts (it may count ones no longer public, so a walk of the episodes can return fewer); null when it does not state one.
rating_countintegernullableListeners who rated the show, 0 when none has; null when the platform shows no count.
platform_specificobjectFields only this platform has, under its ID (platform_specific.<platform>); each null when unknown.
approximate_fieldsstring[]JSON paths of values rounded by the platform, date-only or parsed from display text (rating at one decimal, metrics.rating_count from "2.6K"). [] when all exact.
unknown_fieldsstring[]JSON paths of lists whose [] means unknown rather than none (a source that cannot see them); null already means unknown for every other field. [] when every list is known.
Item errors
Besides the request-level errors every endpoint can return, podcast endpoints return:
| Code | HTTP | Retry | Meaning | What to do |
|---|---|---|---|---|
not_found | 404 | No | The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). | Check the link or ID. Do not retry. |
private_or_unavailable | 403 | No | The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. | Only public items can be fetched. Do not retry. |