Skip to content

Episodes

API #

Implementation to make API calls with.

Parameters:

get_episode #

get_episode(episode_id: str, *, market: MissingOr[str] = MISSING) -> Episode

Get Spotify catalog information for a single episode.

Warning

When not using a user token for auth, market is required. Otherwise you will receive a 404.

Parameters:

Returns:

  • Episode –

    The requested episode.

get_several_episodes #

get_several_episodes(episode_ids: list[str], *, market: MissingOr[str] = MISSING) -> list[Episode]

Get Spotify catalog information for several episodes.

Warning

When not using a user token for auth, market is required. Otherwise you will receive an error.

Parameters:

Returns:

get_users_saved_episodes #

get_users_saved_episodes(*, limit: MissingOr[int] = MISSING, offset: MissingOr[int] = MISSING, market: MissingOr[str] = MISSING) -> Paginator[SavedEpisode]

Get a list of the episodes saved in the current user's 'Your Music' library.

Required Authorization Scope

USER_LIBRARY_READ

Warning

This API endpoint is in beta and could break without warning.

Parameters:

  • limit (int, default: 20 ) –

    The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.

  • offset (int, default: 0 ) –

    The index of the first item to return. Default: 0 (the first item).

  • market (str, default: MISSING ) –

    Only get content available in that market. Must be an ISO 3166-1 alpha-2 country code.

Returns:

remove_users_saved_episodes #

remove_users_saved_episodes(episode_ids: list[str]) -> None

Remove one or more episodes from the current user's 'Your Music' library.

Required Authorization Scope

USER_LIBRARY_MODIFY

Warning

This API endpoint is in beta and could break without warning.

Parameters:

  • episode_ids (list[str]) –

    The IDs of the episodes. Maximum: 50.

check_users_saved_episodes #

check_users_saved_episodes(episode_ids: list[str]) -> list[bool]

Check if one or more episodes are already saved in the current user's 'Your Music' library.

Required Authorization Scope

USER_LIBRARY_READ

Warning

This API endpoint is in beta and could break without warning.

Parameters:

  • episode_ids (list[str]) –

    The IDs of the episodes. Maximum: 50.

Returns:

  • list[bool] –

    A list of booleans dictating whether or not the corresponding episodes are already saved.

SimpleEpisode #

A simplified episode.

audio_preview_url #

audio_preview_url: str | None

A URL to a 30 second preview (MP3 format) of the episode. None if not available.

description #

description: str

A description of the episode. HTML tags are stripped away from this field, use the html_description field in case HTML tags are needed.

html_description #

html_description: str

A description of the episode. This field may contain HTML tags.

duration #

duration: timedelta = Field(alias='duration_ms')

The episode length.

explicit #

explicit: bool

Whether or not the episode has explicit content.

external_urls #

external_urls: ExternalURLs

External URLs for this episode.

href #

href: str

A link to the Web API endpoint providing full details of the episode.

id #

id: str

The Spotify ID for the episode.

images #

images: list[Image]

The cover art for the episode in various sizes, widest first.

is_externally_hosted #

is_externally_hosted: bool

True if the episode is hosted outside of Spotify's CDN. Otherwise False.

is_playable #

is_playable: bool | None = None

True if the episode is playable in the given market. Otherwise False. May be None in some situations.

languages #

languages: list[str]

A list of the languages used in the episode, identified by their ISO 639-1 code.

name #

name: str

The name of the episode.

release_date #

release_date: date

The date the episode was first released.

release_date_precision #

release_date_precision: ReleaseDatePrecision

The precision with which release_date value is known.

resume_point #

resume_point: ResumePoint | None = None

The user's most recent position in the episode.

Required Authorization Scope

USER_READ_PLAYBACK_POSITION

uri #

uri: str

The Spotify URI for the episode.

restrictions #

restrictions: Restrictions | None = None

Present when a content restriction is applied.

Episode #

An episode.

audio_preview_url #

audio_preview_url: str | None

A URL to a 30 second preview (MP3 format) of the episode. None if not available.

description #

description: str

A description of the episode. HTML tags are stripped away from this field, use the html_description field in case HTML tags are needed.

html_description #

html_description: str

A description of the episode. This field may contain HTML tags.

duration #

duration: timedelta = Field(alias='duration_ms')

The episode length.

explicit #

explicit: bool

Whether or not the episode has explicit content.

external_urls #

external_urls: ExternalURLs

External URLs for this episode.

href #

href: str

A link to the Web API endpoint providing full details of the episode.

id #

id: str

The Spotify ID for the episode.

images #

images: list[Image]

The cover art for the episode in various sizes, widest first.

is_externally_hosted #

is_externally_hosted: bool

True if the episode is hosted outside of Spotify's CDN. Otherwise False.

is_playable #

is_playable: bool | None = None

True if the episode is playable in the given market. Otherwise False. May be None in some situations.

languages #

languages: list[str]

A list of the languages used in the episode, identified by their ISO 639-1 code.

name #

name: str

The name of the episode.

release_date #

release_date: date

The date the episode was first released.

release_date_precision #

release_date_precision: ReleaseDatePrecision

The precision with which release_date value is known.

resume_point #

resume_point: ResumePoint | None = None

The user's most recent position in the episode.

Required Authorization Scope

USER_READ_PLAYBACK_POSITION

uri #

uri: str

The Spotify URI for the episode.

restrictions #

restrictions: Restrictions | None = None

Present when a content restriction is applied.

show #

show: SimpleShow

The show on which the episode appears.

SavedEpisode #

Information about an episode saved to a user's 'Your Music' library.

added_at #

added_at: datetime

The date and time the episode was saved.

episode #

episode: Episode

The episode.