# Podcast

Schemas

Podcasts with their publisher, description, cover, rating, categories, episode count and when the latest episode came out.

## Endpoints

2 endpoints return podcasts on Spotify.

- [GETSpotify Podcast API`/v1/spotify/podcast`](https://socialtap.dev/docs/reference/spotify/podcast/index.md)
- [GETSpotify Podcast Search API`/v1/spotify/search_podcasts`](https://socialtap.dev/docs/reference/spotify/search_podcasts/index.md)

## Schema

Single-item endpoints return this object as `data`; list endpoints return an array of them as `data` with a [`page`](https://socialtap.dev/docs/pagination/index.md) object. The standard [`meta`](https://socialtap.dev/docs/reference/index.md#meta) comes with every response.

| Field | Type | Description |
| --- | --- | --- |
| `platform` | `string` | Platform ID (spotify, youtube, …). |
| `id` | `string` | Platform-native show ID (string), the one in its page's URL. |
| `url` | `string` (uri) | Canonical show page URL. |
| `title` | `string` | The show's name as the platform lists it. |
| `description` | `string` or `null` | About the show, as plain text; null when it has none or the platform shows none. |
| `publisher_name` | `string` or `null` | Who publishes the show, as the platform names them; null when it does not. |
| `publisher` | `object` or `null` | The platform account of the publisher; null when the platform names them without an account (always on Spotify). |
| `publisher.id` | `string` or `null` | Platform-native account ID; null when only the handle is known. |
| `publisher.username` | `string` or `null` | Handle without the @; null when the account has none. |
| `publisher.display_name` | `string` or `null` | Display name shown on the profile. |
| `publisher.url` | `string` (uri) or `null` | Canonical profile URL. |
| `publisher.avatar_url` | `string` (uri) or `null` | Profile picture URL. Platform CDN URLs can expire within hours. |
| `publisher.is_verified` | `boolean` or `null` | Platform verification badge; null where the platform has no badge. |
| `cover_url` | `string` (uri) or `null` | Cover art URL at the largest size the platform serves; null when it has none. Platform CDN URLs can expire within hours. |
| `media_type` | `string` or `null` | What its episodes are: audio, video or mixed (both); null when the platform does not say. New values may be added.<br>One of `audio`, `video`, `mixed` |
| `show_type` | `string` or `null` | episodic: 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.<br>One of `episodic`, `serial` |
| `categories` | `string[]` | 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_explicit` | `boolean` or `null` | Marked as holding explicit content by the platform; null when it does not say. |
| `rating` | `number` or `null` | Listeners' 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_at` | `string` (date-time) or `null` | When 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. |
| `metrics` | `object` | Counts at fetch time; null = hidden or not exposed, 0 = zero. |
| `metrics.episode_count` | `integer` or `null` | Episodes 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. |
| `metrics.rating_count` | `integer` or `null` | Listeners who rated the show, 0 when none has; null when the platform shows no count. |
| `platform_specific` | `object` | Fields only this platform has, under its ID (platform_specific.\<platform>); each null when unknown. |
| `approximate_fields` | `string[]` | 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_fields` | `string[]` | 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](https://socialtap.dev/docs/errors/index.md) 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. |

---

[HTML version](https://socialtap.dev/resources/podcast/) · [Docs index for AI agents](https://socialtap.dev/llms.txt) · [All docs in one file](https://socialtap.dev/llms-full.txt)