Episodes Endpoint Reference

Functions

async check_user_saved_episodes(client: SpotanticClient, *, episode_ids: Sequence[SpotifyItemID]) → APICallModel[CheckUserSavedEpisodesRequest, JsonAPIResponse, dict[SpotifyItemID, bool]]

Check if one or more episodes is already saved in the current Spotify user’s ‘Your Episodes’ library.

Deprecated since version 0.1.0: This endpoint is deprecated since 11 February 2026 for new users. Existing users may be able to continue using it. More information on the deprecation can be found in the Spotify API documentation: Update on Developer Access and Platform Security. This endpoint is deprecated. Use Check User’s Saved Items instead.

Parameters:

  • client – SpotanticClient instance.

  • episode_ids – A list of Spotify IDs for the episodes to check.

Returns:

An object containing the request used to obtain the response, the retrieved data and parsed data as model.

async get_episode(client: SpotanticClient, *, episode_id: SpotifyItemID, market: SpotifyMarketID | None = None) → APICallModel[GetEpisodeRequest, JsonAPIResponse, EpisodeModel]

Get Spotify catalog information for a single episode.

Get Spotify catalog information for a single episode identified by its unique Spotify ID.

Parameters:

  • client – SpotanticClient instance.

  • episode_id – The Spotify ID for the episode.

  • market – An ISO 3166-1 alpha-2 country code.

Returns:

An object containing the request used to obtain the response, the retrieved data and parsed data as model.

async get_several_episodes(client: SpotanticClient, *, episode_ids: Sequence[SpotifyItemID], market: SpotifyMarketID | None = None) → APICallModel[GetSeveralEpisodesRequest, JsonAPIResponse, list[EpisodeModel]]

Get Spotify catalog information for several episodes based on their Spotify IDs.

Deprecated since version 0.1.0: This endpoint is deprecated since 11 February 2026 for new users. Existing users may be able to continue using it. More information on the deprecation can be found in the Spotify API documentation: Update on Developer Access and Platform Security.

Parameters:

  • client – SpotanticClient instance.

  • episode_ids – A list of Spotify IDs for the episodes.

  • market – An ISO 3166-1 alpha-2 country code.

Returns:

An object containing the request used to obtain the response, the retrieved data and parsed data as model.

async get_user_saved_episodes(client: SpotanticClient, *, limit: int = 20, offset: int = 0, market: SpotifyMarketID | None = None) → APICallModel[GetUserSavedEpisodesRequest, JsonAPIResponse, PagedResultModel[SavedEpisodeModel]]

Return a list of the episodes saved in the current Spotify user’s library.

Get a list of the episodes saved in the current Spotify user’s library.

Parameters:

  • client – SpotanticClient instance.

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

  • offset – The index of the first item to return. Default: 0 (the first item). Use with limit to get the next set of items.

  • market – An ISO 3166-1 alpha-2 country code.

Returns:

An object containing the request used to obtain the response, the retrieved data and parsed data as model.

async remove_user_saved_episodes(client: SpotanticClient, *, episode_ids: Sequence[SpotifyItemID]) → APICallModel[RemoveUserSavedEpisodesRequest, RawAPIResponse, NoneType]

Remove one or more episodes from the current user’s library.

Deprecated since version 0.1.0: This endpoint is deprecated since 11 February 2026 for new users. Existing users may be able to continue using it. More information on the deprecation can be found in the Spotify API documentation: Update on Developer Access and Platform Security. Use Remove Items from Library instead.

Parameters:

  • client – SpotanticClient instance.

  • episode_ids – A list of Spotify IDs for the episodes to be removed from the user’s library.

Returns:

An object containing the request used to obtain the response and the response.

async save_episodes_for_current_user(client: SpotanticClient, *, episode_ids: Sequence[SpotifyItemID]) → APICallModel[SaveEpisodesForCurrentUserRequest, RawAPIResponse, NoneType]

Save one or more episodes to the current user’s library.

Deprecated since version 0.1.0: This endpoint is deprecated since 11 February 2026 for new users. Existing users may be able to continue using it. More information on the deprecation can be found in the Spotify API documentation: Update on Developer Access and Platform Security. Use Save Items to Library instead.

Parameters:

  • client – SpotanticClient instance.

  • episode_ids – A list of the Spotify IDs for the episodes to be saved to the user’s library.

Returns:

An object containing the request used to obtain the response and the response.

Request models

class CheckUserSavedEpisodesRequest(*, required_scopes: set[AuthScope] = {AuthScope.USER_LIBRARY_READ}, url: HttpUrl | None = None, endpoint: str | None = 'me/episodes/contains', method_type: HTTPMethod = <HTTPMethod.GET>, headers: RequestHeadersModel = <factory>, params: CheckUserSavedEpisodesRequestParams | None = None, body: None = None)

Bases: RequestModel[CheckUserSavedEpisodesRequestParams, NoneType]

Request model for Check User Saved Episodes endpoint.

classmethod build(*, episode_ids: Sequence[SpotifyItemID]) → CheckUserSavedEpisodesRequest

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:

episode_ids – A list of Spotify episode IDs to check for.

Returns:

Validated Request object.

endpoint: str | None

Endpoint associated with the request.

method_type: HTTPMethod

HTTP method for the request.

required_scopes: set[AuthScope]

Required authorization scopes for the request.

class CheckUserSavedEpisodesRequestParams(*, episode_ids: Annotated[Sequence[SpotifyItemID], MaxLen(max_length=50), PlainSerializer(func=sequence_to_comma_separated_str, return_type=str, when_used=always)])

Bases: BaseModel

Params model for Check User Saved Episodes request.

episode_ids: Annotated[Sequence[SpotifyItemID], Field(max_length=50, serialization_alias='ids'), PlainSerializer(sequence_to_comma_separated_str, return_type=str)]

A list of Spotify episode IDs to check for.

class GetEpisodeRequest(*, required_scopes: set[AuthScope] = {AuthScope.USER_READ_PLAYBACK_POSITION}, url: HttpUrl | None = None, endpoint: str | None = None, method_type: HTTPMethod = <HTTPMethod.GET>, headers: RequestHeadersModel = <factory>, params: GetEpisodeRequestParams | None = None, body: None = None)

Bases: RequestModel[GetEpisodeRequestParams, NoneType]

Request model for Get Episode endpoint.

classmethod build(*, episode_id: SpotifyItemID, market: SpotifyMarketID | None = None) → GetEpisodeRequest

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:

  • episode_id – The Spotify ID of the episode.

  • market – An ISO 3166-1 alpha-2 country code.

Returns:

Validated Request object.

method_type: HTTPMethod

HTTP method for the request.

required_scopes: set[AuthScope]

Required authorization scopes for the request.

class GetEpisodeRequestParams(*, episode_id: SpotifyItemID, market: SpotifyMarketID | None = None)

Bases: BaseModel

Params model for Get Episode request.

episode_id: SpotifyItemID

The Spotify ID of the episode.

market: SpotifyMarketID | None

An ISO 3166-1 alpha-2 country code.

class GetSeveralEpisodesRequest(*, required_scopes: set[AuthScope] = {AuthScope.USER_READ_PLAYBACK_POSITION}, url: HttpUrl | None = None, endpoint: str | None = 'episodes', method_type: HTTPMethod = <HTTPMethod.GET>, headers: RequestHeadersModel = <factory>, params: GetSeveralEpisodesRequestParams | None = None, body: None = None)

Bases: RequestModel[GetSeveralEpisodesRequestParams, NoneType]

Request model for Get Several Episodes endpoint.

classmethod build(*, episode_ids: Sequence[SpotifyItemID], market: SpotifyMarketID | None = None) → GetSeveralEpisodesRequest

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:

  • episode_ids – A list of Spotify episode IDs to retrieve.

  • market – An ISO 3166-1 alpha-2 country code.

Returns:

Validated Request object.

endpoint: str | None

Endpoint associated with the request.

method_type: HTTPMethod

HTTP method for the request.

required_scopes: set[AuthScope]

Required authorization scopes for the request.

class GetSeveralEpisodesRequestParams(*, episode_ids: Annotated[Sequence[SpotifyItemID], MaxLen(max_length=50), PlainSerializer(func=sequence_to_comma_separated_str, return_type=str, when_used=always)], market: SpotifyMarketID | None = None)

Bases: BaseModel

Params model for Get Several Episodes request.

episode_ids: Annotated[Sequence[SpotifyItemID], Field(max_length=50, serialization_alias='ids'), PlainSerializer(sequence_to_comma_separated_str, return_type=str)]

A list of Spotify episode IDs to retrieve.

market: SpotifyMarketID | None

An ISO 3166-1 alpha-2 country code.

class GetUserSavedEpisodesRequest(*, required_scopes: set[AuthScope] = {AuthScope.USER_LIBRARY_READ, AuthScope.USER_READ_PLAYBACK_POSITION}, url: HttpUrl | None = None, endpoint: str | None = 'me/episodes', method_type: HTTPMethod = <HTTPMethod.GET>, headers: RequestHeadersModel = <factory>, params: GetUserSavedEpisodesRequestParams | None = None, body: None = None)

Bases: RequestModel[GetUserSavedEpisodesRequestParams, NoneType]

Request model for Get User Saved Episodes endpoint.

classmethod build(*, limit: int = 20, offset: int = 0, market: SpotifyMarketID | None = None) → GetUserSavedEpisodesRequest

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:

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

  • offset – The index of the first item to return. Default: 0 (the first item). Use with limit to get the next set of items.

  • market – An ISO 3166-1 alpha-2 country code.

Returns:

Validated Request object.

endpoint: str | None

Endpoint associated with the request.

method_type: HTTPMethod

HTTP method for the request.

required_scopes: set[AuthScope]

Required authorization scopes for the request.

class GetUserSavedEpisodesRequestParams(*, limit: Annotated[int, Ge(ge=1), Le(le=50)], offset: int, market: SpotifyMarketID | None = None)

Bases: BaseModel

Params model for Get User Saved Episodes request.

limit: Annotated[int, Field(ge=1, le=50)]

The maximum number of items to return.

market: SpotifyMarketID | None

An ISO 3166-1 alpha-2 country code.

offset: int

The index of the first item to return.

class RemoveUserSavedEpisodesRequest(*, required_scopes: set[AuthScope] = {AuthScope.USER_LIBRARY_MODIFY}, url: HttpUrl | None = None, endpoint: str | None = 'me/episodes', method_type: HTTPMethod = <HTTPMethod.DELETE>, headers: RequestHeadersModel = <factory>, params: RemoveUserSavedEpisodesRequestParams | None = None, body: None = None)

Bases: RequestModel[RemoveUserSavedEpisodesRequestParams, NoneType]

Request model for Remove User Saved Episodes endpoint.

classmethod build(*, episode_ids: Sequence[SpotifyItemID]) → RemoveUserSavedEpisodesRequest

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:

episode_ids – A list of Spotify IDs for the episodes to be removed from the user’s library.

Returns:

Validated Request object.

endpoint: str | None

Endpoint associated with the request.

method_type: HTTPMethod

HTTP method for the request.

required_scopes: set[AuthScope]

Required authorization scopes for the request.

class RemoveUserSavedEpisodesRequestParams(*, episode_ids: Annotated[Sequence[SpotifyItemID], MaxLen(max_length=50), PlainSerializer(func=sequence_to_comma_separated_str, return_type=str, when_used=always)])

Bases: BaseModel

Params model for Remove User Saved Episodes request.

episode_ids: Annotated[Sequence[SpotifyItemID], Field(max_length=50, serialization_alias='ids'), PlainSerializer(sequence_to_comma_separated_str, return_type=str)]

A list of Spotify IDs for the episodes to be removed from the user’s library.

class SaveEpisodesForCurrentUserRequest(*, required_scopes: set[AuthScope] = {AuthScope.USER_LIBRARY_MODIFY}, url: HttpUrl | None = None, endpoint: str | None = 'me/episodes', method_type: HTTPMethod = <HTTPMethod.PUT>, headers: RequestHeadersModel = <factory>, params: SaveEpisodesForCurrentUserRequestParams | None = None, body: None = None)

Bases: RequestModel[SaveEpisodesForCurrentUserRequestParams, NoneType]

Request model for Save Episodes For Current User endpoint.

classmethod build(*, episode_ids: Sequence[SpotifyItemID]) → SaveEpisodesForCurrentUserRequest

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:

episode_ids – A list of the Spotify IDs for the episodes to be saved to the user’s library.

Returns:

Validated Request object.

endpoint: str | None

Endpoint associated with the request.

method_type: HTTPMethod

HTTP method for the request.

required_scopes: set[AuthScope]

Required authorization scopes for the request.

class SaveEpisodesForCurrentUserRequestParams(*, episode_ids: Annotated[Sequence[SpotifyItemID], MaxLen(max_length=50), PlainSerializer(func=sequence_to_comma_separated_str, return_type=str, when_used=always)])

Bases: BaseModel

Params model for Save Episodes For Current User request.

episode_ids: Annotated[Sequence[SpotifyItemID], Field(max_length=50, serialization_alias='ids'), PlainSerializer(sequence_to_comma_separated_str, return_type=str)]

A list of the Spotify IDs for the episodes to be saved to the user’s library.

Response models

class GetSeveralEpisodesResponse(*, episodes: list[EpisodeModel])

Bases: BaseModel

Response model for Get Several Episodes endpoint.

episodes: list[EpisodeModel]

List of episodes.