Albums Endpoint Reference

Functions

async check_user_saved_albums(client: SpotanticClient, *, album_ids: Sequence[SpotifyItemID]) → APICallModel[CheckUserSavedAlbumsRequest, JsonAPIResponse, dict[SpotifyItemID, bool]]

Check if one or more albums is already saved in the current Spotify user’s ‘Your Music’ 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.

  • album_ids – A list of Spotify IDs for the albums to check.

Returns:

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

async get_album(client: SpotanticClient, *, album_id: SpotifyItemID, market: SpotifyMarketID | None = None) → APICallModel[GetAlbumRequest, JsonAPIResponse, AlbumModel]

Get Spotify catalog information for a single album.

Parameters:

  • client – SpotanticClient instance.

  • album_id – The Spotify ID for the album.

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

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

Parameters:

  • client – SpotanticClient instance.

  • album_id – The Spotify ID for the album.

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

Get a list of new album releases featured in Spotify (shown, for example, on a Spotify player’s “Browse” tab).

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.

  • 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 get_several_albums(client: SpotanticClient, *, album_ids: Sequence[SpotifyItemID], market: SpotifyMarketID | None = None) → APICallModel[GetSeveralAlbumsRequest, JsonAPIResponse, list[AlbumModel]]

Get Spotify catalog information for multiple albums identified by 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.

  • album_ids – A list of Spotify artist IDs to retrieve.

  • 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_albums(client: SpotanticClient, *, limit: int = 20, offset: int = 0, market: SpotifyMarketID | None = None) → APICallModel[GetUserSavedAlbumsRequest, JsonAPIResponse, PagedResultModel[SavedAlbumModel]]

Get a list of the albums saved in the current Spotify user’s ‘Your Music’ 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_albums(client: SpotanticClient, *, album_ids: Sequence[SpotifyItemID]) → APICallModel[RemoveUserSavedAlbumsRequest, RawAPIResponse, NoneType]

Remove one or more albums from the current user’s ‘Your Music’ 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.

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

Returns:

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

async save_albums_for_current_user(client: SpotanticClient, *, album_ids: Sequence[SpotifyItemID]) → APICallModel[SaveAlbumsForCurrentUserRequest, RawAPIResponse, NoneType]

Save one or more albums to the current user’s ‘Your Music’ 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.

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

Returns:

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

Request models

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

Bases: RequestModel[CheckUserSavedAlbumsRequestParams, NoneType]

Request model for Check User Saved Albums endpoint.

classmethod build(*, album_ids: Sequence[SpotifyItemID]) → CheckUserSavedAlbumsRequest

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:

album_ids – A list of Spotify IDs for the albums to check.

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 CheckUserSavedAlbumsRequestParams(*, album_ids: Annotated[Sequence[SpotifyItemID], MaxLen(max_length=20), PlainSerializer(func=sequence_to_comma_separated_str, return_type=str, when_used=always)])

Bases: BaseModel

Params model for Check User Saved Albums request.

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

A list of Spotify IDs for the albums to check.

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

Bases: RequestModel[GetAlbumRequestParams, NoneType]

Request model for Get Album endpoint.

classmethod build(*, album_id: SpotifyItemID, market: SpotifyMarketID | None = None) → GetAlbumRequest

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:

  • album_id – The Spotify ID for the album.

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

Returns:

Validated Request object.

method_type: HTTPMethod

HTTP method for the request.

class GetAlbumRequestParams(*, album_id: SpotifyItemID, market: SpotifyMarketID | None = None)

Bases: BaseModel

Params model for Get Album request.

album_id: SpotifyItemID

The Spotify ID for the album.

market: SpotifyMarketID | None

An ISO 3166-1 alpha-2 country code.

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

Bases: RequestModel[GetAlbumTracksRequestParams, NoneType]

Request model for Get Album Tracks endpoint.

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

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:

  • album_id – The Spotify ID for the album.

  • limit – The maximum number of items to return.

  • offset – The index of the first item to return.

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

Returns:

Validated Request object.

method_type: HTTPMethod

HTTP method for the request.

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

Bases: BaseModel

Params model for Get Album Tracks request.

album_id: SpotifyItemID

The Spotify ID for the album.

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 GetNewReleasesRequest(*, required_scopes: set[AuthScope] = <factory>, url: HttpUrl | None = None, endpoint: str | None = 'browse/new-releases', method_type: HTTPMethod = <HTTPMethod.GET>, headers: RequestHeadersModel = <factory>, params: GetNewReleasesRequestParams | None = None, body: None = None)

Bases: RequestModel[GetNewReleasesRequestParams, NoneType]

Request model for Get New Releases endpoint.

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

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.

  • offset – The index of the first item to return.

Returns:

Validated Request object.

endpoint: str | None

Endpoint associated with the request.

method_type: HTTPMethod

HTTP method for the request.

class GetNewReleasesRequestParams(*, limit: Annotated[int, Ge(ge=1), Le(le=50)], offset: int)

Bases: BaseModel

Params model for Get New Releases 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 GetSeveralAlbumsRequest(*, required_scopes: set[AuthScope] = <factory>, url: HttpUrl | None = None, endpoint: str | None = 'albums', method_type: HTTPMethod = <HTTPMethod.GET>, headers: RequestHeadersModel = <factory>, params: GetSeveralAlbumsRequestParams | None = None, body: None = None)

Bases: RequestModel[GetSeveralAlbumsRequestParams, NoneType]

Request model for Get Several Albums endpoint.

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

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:

  • album_ids – A list of Spotify artist 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.

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

Bases: BaseModel

Params model for Get Several Albums request.

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

A list of Spotify artist IDs to retrieve.

market: SpotifyMarketID | None

An ISO 3166-1 alpha-2 country code.

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

Bases: RequestModel[GetUserSavedAlbumsRequestParams, NoneType]

Request model for Get User Saved Albums endpoint.

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

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.

  • offset – The index of the first item to return.

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

Bases: BaseModel

Params model for Get User Saved Albums 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 RemoveUserSavedAlbumsRequest(*, required_scopes: set[AuthScope] = {AuthScope.USER_LIBRARY_MODIFY}, url: HttpUrl | None = None, endpoint: str | None = 'me/albums', method_type: HTTPMethod = <HTTPMethod.DELETE>, headers: RequestHeadersModel = <factory>, params: RemoveUserSavedAlbumsRequestParams | None = None, body: None = None)

Bases: RequestModel[RemoveUserSavedAlbumsRequestParams, NoneType]

Request model for Remove User Saved Albums endpoint.

classmethod build(*, album_ids: Sequence[SpotifyItemID]) → RemoveUserSavedAlbumsRequest

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:

album_ids – A list of Spotify IDs for the albums 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 RemoveUserSavedAlbumsRequestParams(*, album_ids: Annotated[Sequence[SpotifyItemID], MaxLen(max_length=20), PlainSerializer(func=sequence_to_comma_separated_str, return_type=str, when_used=always)])

Bases: BaseModel

Params model for Remove User Saved Albums request.

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

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

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

Bases: RequestModel[SaveAlbumsForCurrentUserRequestParams, NoneType]

Request model for Save Albums For Current User endpoint.

classmethod build(*, album_ids: Sequence[SpotifyItemID]) → SaveAlbumsForCurrentUserRequest

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:

album_ids – A list of the Spotify IDs for the albums 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 SaveAlbumsForCurrentUserRequestParams(*, album_ids: Annotated[Sequence[SpotifyItemID], MaxLen(max_length=20), PlainSerializer(func=sequence_to_comma_separated_str, return_type=str, when_used=always)])

Bases: BaseModel

Params model for Save Albums For Current User request.

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

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

Response models

class GetNewReleasesResponse(*, albums: PagedResultModel[SimplifiedAlbumModel])

Bases: BaseModel

Response model for Get New Releases endpoint.

albums: PagedResultModel[SimplifiedAlbumModel]

List of albums.

class GetSeveralAlbumsResponse(*, albums: list[AlbumModel])

Bases: BaseModel

Response model for Get Several Albums endpoint.

albums: list[AlbumModel]

List of albums.