Shows Endpoint Reference

Functions

async check_user_saved_shows(client: SpotanticClient, *, show_ids: Sequence[SpotifyItemID]) → APICallModel[CheckUserSavedShowsRequest, JsonAPIResponse, dict[SpotifyItemID, bool]]

Check if one or more shows is already saved in the current Spotify 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. This endpoint is deprecated. Use Check User’s Saved Items instead.

Parameters:

  • client – SpotanticClient instance.

  • show_ids – A list of the Spotify IDs for the shows.

Returns:

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

async get_several_shows(client: SpotanticClient, *, show_ids: Sequence[SpotifyItemID], market: SpotifyMarketID | None = None) → APICallModel[GetSeveralShowsRequest, JsonAPIResponse, list[SimplifiedShowModel]]

Get Spotify catalog information for several shows 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.

  • show_ids – A list of the Spotify IDs for the shows.

  • 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_show(client: SpotanticClient, *, show_id: SpotifyItemID, market: SpotifyMarketID | None = None) → APICallModel[GetShowRequest, JsonAPIResponse, ShowModel]

Return information about a show.

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

Parameters:

  • client – SpotanticClient instance.

  • show_id – The Spotify ID for the show.

  • 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_show_episodes(client: SpotanticClient, *, show_id: SpotifyItemID, limit: int = 20, offset: int = 0, market: SpotifyMarketID | None = None) → APICallModel[GetShowEpisodesRequest, JsonAPIResponse, PagedResultModel[SimplifiedEpisodeModel]]

Return episodes for a show.

Get Spotify catalog information about an show’s episodes. Optional parameters can be used to limit the number of episodes returned.

Parameters:

  • client – SpotanticClient instance.

  • show_id – The Spotify ID for the show.

  • 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 get_user_saved_shows(client: SpotanticClient, *, limit: int = 20, offset: int = 0) → APICallModel[GetUserSavedShowsRequest, JsonAPIResponse, PagedResultModel[SavedShowModel]]

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

Get a list of shows saved in the current Spotify user’s library. Optional parameters can be used to limit the number of shows returned.

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.

Returns:

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

async remove_user_saved_shows(client: SpotanticClient, *, show_ids: Sequence[SpotifyItemID], market: SpotifyMarketID | None = None) → APICallModel[RemoveUserSavedShowsRequest, RawAPIResponse, NoneType]

Delete one or more shows from current Spotify 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.

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

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

Returns:

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

async save_shows_for_current_user(client: SpotanticClient, *, show_ids: Sequence[SpotifyItemID]) → APICallModel[SaveShowsForCurrentUserRequest, RawAPIResponse, NoneType]

Save one or more shows to current Spotify 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.

  • show_ids – A list of the Spotify IDs for the shows 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 CheckUserSavedShowsRequest(*, required_scopes: set[AuthScope] = {AuthScope.USER_LIBRARY_READ}, url: HttpUrl | None = None, endpoint: str | None = 'me/shows/contains', method_type: HTTPMethod = <HTTPMethod.GET>, headers: RequestHeadersModel = <factory>, params: CheckUserSavedShowsRequestParams | None = None, body: None = None)

Bases: RequestModel[CheckUserSavedShowsRequestParams, NoneType]

Request model for Check User Saved Shows endpoint.

classmethod build(*, show_ids: Sequence[SpotifyItemID]) → CheckUserSavedShowsRequest

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:

show_ids – A list of the Spotify IDs for the shows.

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 CheckUserSavedShowsRequestParams(*, show_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 Shows request.

show_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 shows.

class GetSeveralShowsRequest(*, required_scopes: set[AuthScope] = <factory>, url: HttpUrl | None = None, endpoint: str | None = 'shows', method_type: HTTPMethod = <HTTPMethod.GET>, headers: RequestHeadersModel = <factory>, params: GetSeveralShowsRequestParams | None = None, body: None = None)

Bases: RequestModel[GetSeveralShowsRequestParams, NoneType]

Request model for Get Several Shows endpoint.

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

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:

  • show_ids – A list of the Spotify IDs for the shows.

  • 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.

class GetSeveralShowsRequestParams(*, show_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 Shows request.

market: SpotifyMarketID | None

An ISO 3166-1 alpha-2 country code.

show_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 shows.

class GetShowEpisodesRequest(*, 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: GetShowEpisodesRequestParams | None = None, body: None = None)

Bases: RequestModel[GetShowEpisodesRequestParams, NoneType]

Request model for Get Show Episodes endpoint.

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

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:

  • show_id – The Spotify ID for the show.

  • 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.

method_type: HTTPMethod

HTTP method for the request.

required_scopes: set[AuthScope]

Required authorization scopes for the request.

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

Bases: BaseModel

Params model for Get Show 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.

show_id: SpotifyItemID

The Spotify ID for the show.

class GetShowRequest(*, 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: GetShowRequestParams | None = None, body: None = None)

Bases: RequestModel[GetShowRequestParams, NoneType]

Request model for Get Show endpoint.

classmethod build(*, show_id: SpotifyItemID, market: SpotifyMarketID | None = None) → GetShowRequest

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:

  • show_id – The Spotify ID for the show.

  • 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 GetShowRequestParams(*, show_id: SpotifyItemID, market: SpotifyMarketID | None = None)

Bases: BaseModel

Params model for Get Show request.

market: SpotifyMarketID | None

An ISO 3166-1 alpha-2 country code.

show_id: SpotifyItemID

The Spotify ID for the show.

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

Bases: RequestModel[GetUserSavedShowsRequestParams, NoneType]

Request model for Get User Saved Shows endpoint.

classmethod build(*, limit: int = 20, offset: int = 0) → GetUserSavedShowsRequest

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).

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 GetUserSavedShowsRequestParams(*, limit: Annotated[int, Ge(ge=1), Le(le=50)], offset: int)

Bases: BaseModel

Params model for Get User Saved Shows request.

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

The maximum number of items to return.

offset: int

The index of the first item to return.

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

Bases: RequestModel[RemoveUserSavedShowsRequestParams, NoneType]

Request model for Remove User Saved Shows endpoint.

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

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:

  • show_ids – A list of the Spotify IDs for the shows.

  • 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 RemoveUserSavedShowsRequestParams(*, show_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 Remove User Saved Shows request.

market: SpotifyMarketID | None

An ISO 3166-1 alpha-2 country code.

show_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 shows.

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

Bases: RequestModel[SaveShowsForCurrentUserRequestParams, NoneType]

Request model for Save Shows For Current User endpoint.

classmethod build(*, show_ids: Sequence[SpotifyItemID]) → SaveShowsForCurrentUserRequest

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:

show_ids – A list of the Spotify IDs for the shows.

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 SaveShowsForCurrentUserRequestParams(*, show_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 Shows For Current User request.

show_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 shows.

Response models

class GetSeveralShowsResponse(*, shows: list[SimplifiedShowModel])

Bases: BaseModel

Response model for Get Several Shows endpoint.

shows: list[SimplifiedShowModel]

List of shows.