Users Endpoint Reference

Functions

async check_if_current_user_follows_playlist(client: SpotanticClient, *, playlist_id: SpotifyItemID) → APICallModel[CheckIfCurrentUserFollowsPlaylistRequest, JsonAPIResponse, bool]

Check to see if the current user is following a specified playlist.

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.

  • playlist_id – The Spotify ID for the playlist.

Returns:

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

async check_if_user_follows_artists_or_users(client: SpotanticClient, *, item_type: SpotifyItemType, item_ids: Sequence[str]) → APICallModel[CheckIfUserFollowsArtistsOrUsersRequest, JsonAPIResponse, dict[SpotifyItemID, bool]]

Check to see if the current user is following one or more artists or other Spotify users.

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.

  • item_type – The type of item to check. Valid values are ‘artist’ or ‘user’.

  • item_ids – A list of Spotify IDs for the artists or users to check.

Returns:

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

async follow_artists_or_users(client: SpotanticClient, *, item_type: SpotifyItemType, item_ids: Sequence[SpotifyItemID]) → APICallModel[FollowArtistsOrUsersRequest, RawAPIResponse, NoneType]

Add the current user as a follower of one or more artists or other Spotify users.

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.

  • item_type – The type of item to follow.

  • item_ids – A list of Spotify IDs for the artists or users to follow.

Returns:

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

async follow_playlist(client: SpotanticClient, *, playlist_id: SpotifyItemID, public: bool = True) → APICallModel[FollowPlaylistRequest, RawAPIResponse, NoneType]

Add the current user as a follower of a playlist.

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.

  • playlist_id – The Spotify ID for the playlist to follow.

  • public – If True the playlist will be included in the user’s public playlists, if False it will be private. Default is True.

Returns:

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

async get_current_user_profile(client: SpotanticClient) → APICallModel[GetCurrentUserProfileRequest, JsonAPIResponse, CurrentUserModel]

Get detailed profile information about the current user (including the current user’s username).

Parameters:

client – SpotanticClient instance.

Returns:

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

async get_followed_artists(client: SpotanticClient, *, item_type: SpotifyItemType = SpotifyItemType.ARTIST, after: SpotifyItemID | None = None, limit: int | None = 20) → APICallModel[GetFollowedArtistsRequest, JsonAPIResponse, PagedResultWithCursorsModel[ArtistModel]]

Get the current user’s followed artists.

Parameters:

  • client – SpotanticClient instance.

  • item_type – The ID type: currently only ‘artist’ is supported.

  • after – The last artist ID retrieved from the previous request. Used to get the next set of results.

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

Returns:

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

async get_user_profile(client: SpotanticClient, *, user_id: str) → APICallModel[GetUserProfileRequest, JsonAPIResponse, UserModel]

Get public profile information about a Spotify user.

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.

  • user_id – The Spotify user ID for the user.

Returns:

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

async get_user_top_items(client: SpotanticClient, *, item_type: Literal[GetUserTopItemsType.ARTISTS], time_range: GetUserTopItemsTimeRange, limit: int = 20, offset: int = 0) → APICallModel[GetUserTopItemsRequest, JsonAPIResponse, PagedResultModel[ArtistModel]]
async get_user_top_items(client: SpotanticClient, *, item_type: Literal[GetUserTopItemsType.TRACKS], time_range: GetUserTopItemsTimeRange, limit: int = 20, offset: int = 0) → APICallModel[GetUserTopItemsRequest, JsonAPIResponse, PagedResultModel[TrackModel]]

Get the current user’s top artists or tracks based on calculated affinity.

Parameters:

  • client – SpotanticClient instance.

  • item_type – The type of item to retrieve (artists or tracks).

  • time_range – Over what time frame the affinities are computed.

  • 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 unfollow_artists_or_users(client: SpotanticClient, *, item_type: SpotifyItemType, item_ids: Sequence[str]) → APICallModel[UnfollowArtistsOrUsersRequest, RawAPIResponse, NoneType]

Remove the current user as a follower of one or more artists or other Spotify users.

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.

  • item_type – The type of the items to unfollow. Must be either ‘artist’ or ‘user’.

  • item_ids – A sequence of Spotify IDs for the artists or users to unfollow. Maximum of 50 IDs.

Returns:

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

async unfollow_playlist(client: SpotanticClient, *, playlist_id: SpotifyItemID) → APICallModel[UnfollowPlaylistRequest, RawAPIResponse, NoneType]

Remove the current user as a follower of a playlist.

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.

  • playlist_id – The Spotify ID of the playlist to unfollow.

Returns:

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

Request models

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

Bases: RequestModel[CheckIfCurrentUserFollowsPlaylistRequestParams, NoneType]

Request model for Check If Current User Follows Playlist endpoint.

classmethod build(*, playlist_id: SpotifyItemID) → CheckIfCurrentUserFollowsPlaylistRequest

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:

playlist_id – The Spotify ID for the playlist.

Returns:

Validated Request object.

method_type: HTTPMethod

HTTP method for the request.

class CheckIfCurrentUserFollowsPlaylistRequestParams(*, playlist_id: SpotifyItemID)

Bases: BaseModel

Params model for Check If Current User Follows Playlist request.

playlist_id: SpotifyItemID

The Spotify ID for the playlist.

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

Bases: RequestModel[CheckIfUserFollowsArtistsOrUsersRequestParams, NoneType]

Request model for Check If User Follows Artists Or Users endpoint.

classmethod build(*, item_type: SpotifyItemType, item_ids: Sequence[str]) → CheckIfUserFollowsArtistsOrUsersRequest

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:

  • item_type – The item type: artist or user.

  • item_ids – A list of the Spotify IDs for the artists or users.

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 CheckIfUserFollowsArtistsOrUsersRequestParams(*, item_type: SpotifyItemType, item_ids: Annotated[Sequence[str] | None, MaxLen(max_length=50), PlainSerializer(func=sequence_to_comma_separated_str, return_type=str, when_used=always)] = None)

Bases: BaseModel

Params model for Check If User Follows Artists Or Users request.

classmethod validate_type_param(value: SpotifyItemType) → SpotifyItemType

Validates that the type parameter is either artist or user.

Parameters:

value – The value to validate.

Returns:

The validated value.

item_ids: Annotated[Sequence[str] | None, Field(max_length=50, serialization_alias='ids'), PlainSerializer(sequence_to_comma_separated_str, return_type=str)]

A list of the Spotify IDs for the artists or users.

item_type: SpotifyItemType

artist or user.

Type:

The item type

class FollowArtistsOrUsersRequest(*, required_scopes: set[AuthScope] = {AuthScope.USER_FOLLOW_MODIFY}, url: HttpUrl | None = None, endpoint: str | None = 'me/following', method_type: HTTPMethod = <HTTPMethod.PUT>, headers: RequestHeadersModel = RequestHeadersModel(content_type='application/json', content_length=None, content_encoding=None, content_language=None), params: FollowArtistsOrUsersRequestParams | None = None, body: FollowArtistsOrUsersRequestBody | None = None)

Bases: RequestModel[FollowArtistsOrUsersRequestParams, FollowArtistsOrUsersRequestBody]

Request model for Follow Artists Or Users endpoint.

classmethod build(*, item_type: SpotifyItemType, item_ids: Sequence[str]) → FollowArtistsOrUsersRequest

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:

  • item_type – The type of item to follow.

  • item_ids – A list of the Spotify IDs for the artists or users.

Returns:

Validated Request object.

endpoint: str | None

Endpoint associated with the request.

headers: RequestHeadersModel

Headers for the request.

method_type: HTTPMethod

HTTP method for the request.

required_scopes: set[AuthScope]

Required authorization scopes for the request.

class FollowArtistsOrUsersRequestBody(*, item_ids: Annotated[Sequence[str] | None, MaxLen(max_length=50)] = None)

Bases: RequestBodyJsonModel

Body model for Follow Artists Or Users request.

item_ids: Annotated[Sequence[str] | None, Field(max_length=50, serialization_alias='ids')]

A list of the Spotify IDs for the artists or users.

class FollowArtistsOrUsersRequestParams(*, item_type: SpotifyItemType, item_ids: Annotated[Sequence[str] | None, MaxLen(max_length=50), PlainSerializer(func=sequence_to_comma_separated_str, return_type=str, when_used=always)] = None)

Bases: BaseModel

Params model for Follow Artists Or Users request.

classmethod validate_type_param(value: SpotifyItemType) → SpotifyItemType

Validates that the type parameter is either artist or user.

Parameters:

value – The value to validate.

Returns:

The validated value.

item_ids: Annotated[Sequence[str] | None, Field(max_length=50, serialization_alias='ids'), PlainSerializer(sequence_to_comma_separated_str, return_type=str)]

A list of the Spotify IDs for the artists or users.

item_type: SpotifyItemType

The type of item to follow.

class FollowPlaylistRequest(*, required_scopes: set[AuthScope] = {AuthScope.PLAYLIST_MODIFY_PRIVATE, AuthScope.PLAYLIST_MODIFY_PUBLIC}, url: HttpUrl | None = None, endpoint: str | None = None, method_type: HTTPMethod = <HTTPMethod.PUT>, headers: RequestHeadersModel = RequestHeadersModel(content_type='application/json', content_length=None, content_encoding=None, content_language=None), params: FollowPlaylistRequestParams | None = None, body: FollowPlaylistRequestBody | None = None)

Bases: RequestModel[FollowPlaylistRequestParams, FollowPlaylistRequestBody]

Request model for Follow Playlist endpoint.

classmethod build(*, playlist_id: SpotifyItemID, public: bool = True) → FollowPlaylistRequest

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:

  • playlist_id – The Spotify ID for the playlist.

  • public – If true the playlist will be followed publicly. If false it will be followed privately.

Returns:

Validated Request object.

headers: RequestHeadersModel

Headers for the request.

method_type: HTTPMethod

HTTP method for the request.

required_scopes: set[AuthScope]

Required authorization scopes for the request.

class FollowPlaylistRequestBody(*, public: bool | None = None)

Bases: RequestBodyJsonModel

Body model for Follow Playlist request.

public: bool | None

If true the playlist will be followed publicly. If false it will be followed privately.

class FollowPlaylistRequestParams(*, playlist_id: SpotifyItemID)

Bases: BaseModel

Params model for Follow Playlist request.

playlist_id: SpotifyItemID

The Spotify ID for the playlist.

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

Bases: RequestModel[NoneType, NoneType]

Request model for Get Current User Profile endpoint.

classmethod build() → GetCurrentUserProfileRequest

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.

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 GetFollowedArtistsRequest(*, required_scopes: set[AuthScope] = {AuthScope.USER_FOLLOW_READ}, url: HttpUrl | None = None, endpoint: str | None = 'me/following', method_type: HTTPMethod = <HTTPMethod.GET>, headers: RequestHeadersModel = <factory>, params: GetFollowedArtistsRequestParams | None = None, body: None = None)

Bases: RequestModel[GetFollowedArtistsRequestParams, NoneType]

Request model for Get Followed Artists endpoint.

classmethod build(*, item_type: SpotifyItemType = SpotifyItemType.ARTIST, after: SpotifyItemID | None = None, limit: int | None = None) → GetFollowedArtistsRequest

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:

  • item_type – The item type.

  • after – The last artist ID retrieved from the previous request.

  • limit – The maximum number of artists to return.

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 GetFollowedArtistsRequestParams(*, item_type: SpotifyItemType, after: SpotifyItemID | None = None, limit: Annotated[int | None, Ge(ge=1), Le(le=50)] = None)

Bases: BaseModel

Params model for Get Followed Artists request.

classmethod validate_type_param(value: SpotifyItemType) → SpotifyItemType

Validates that the type parameter is artist.

Parameters:

value – The value to validate.

Returns:

The validated value.

after: SpotifyItemID | None

The last artist ID retrieved from the previous request.

item_type: SpotifyItemType

The item type.

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

The maximum number of artists to return.

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

Bases: RequestModel[GetUserProfileRequestParams, NoneType]

Request model for Get User Profile endpoint.

classmethod build(*, user_id: str) → GetUserProfileRequest

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:

user_id – The Spotify user ID of the user profile to retrieve.

Returns:

Validated Request object.

method_type: HTTPMethod

HTTP method for the request.

class GetUserProfileRequestParams(*, user_id: str)

Bases: BaseModel

Params model for Get User Profile request.

user_id: str

The Spotify user ID of the user profile to retrieve.

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

Bases: RequestModel[GetUserTopItemsRequestParams, NoneType]

Request model for Get User Top Items endpoint.

classmethod build(*, item_type: GetUserTopItemsType, time_range: GetUserTopItemsTimeRange = GetUserTopItemsTimeRange.MEDIUM_TERM, limit: int = 20, offset: int = 0) → GetUserTopItemsRequest

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:

  • item_type – The type of top items to retrieve.

  • time_range – The time range over which to retrieve top items.

  • limit – The maximum number of items to return.

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

Returns:

Validated Request object.

method_type: HTTPMethod

HTTP method for the request.

required_scopes: set[AuthScope]

Required authorization scopes for the request.

class GetUserTopItemsRequestParams(*, item_type: GetUserTopItemsType, time_range: GetUserTopItemsTimeRange, limit: Annotated[int, Ge(ge=1), Le(le=50)], offset: Annotated[int, Ge(ge=0)])

Bases: BaseModel

Params model for Get User Top Items request.

item_type: GetUserTopItemsType

The type of top items to retrieve.

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

The maximum number of items to return.

offset: Annotated[int, Field(ge=0)]

The index of the first item to return.

time_range: GetUserTopItemsTimeRange

The time range over which to retrieve top items.

class GetUserTopItemsTimeRange(*values)

Bases: str, Enum

The time range over which to retrieve top items.

LONG_TERM = 'long_term'

Long-term. ~1 year of data.

MEDIUM_TERM = 'medium_term'

Medium-term. Approximately last 6 months.

SHORT_TERM = 'short_term'

Short-term. Approximately last 4 weeks.

class GetUserTopItemsType(*values)

Bases: str, Enum

The type of top items to retrieve.

ARTISTS = 'artists'

The user’s top artists.

TRACKS = 'tracks'

The user’s top tracks.

class UnfollowArtistsOrUsersRequest(*, required_scopes: set[AuthScope] = {AuthScope.USER_FOLLOW_MODIFY}, url: HttpUrl | None = None, endpoint: str | None = 'me/following', method_type: HTTPMethod = <HTTPMethod.DELETE>, headers: RequestHeadersModel = RequestHeadersModel(content_type='application/json', content_length=None, content_encoding=None, content_language=None), params: UnfollowArtistsOrUsersRequestParams | None = None, body: UnfollowArtistsOrUsersRequestBody | None = None)

Bases: RequestModel[UnfollowArtistsOrUsersRequestParams, UnfollowArtistsOrUsersRequestBody]

Request model for Unfollow Artists or Users endpoint.

classmethod build(*, item_type: SpotifyItemType, item_ids: Sequence[str]) → UnfollowArtistsOrUsersRequest

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:

  • item_type – The type of the items to unfollow.

  • item_ids – A sequence of Spotify IDs for the artists or users to unfollow.

Returns:

Validated Request object.

endpoint: str | None

Endpoint associated with the request.

headers: RequestHeadersModel

Headers for the request.

method_type: HTTPMethod

HTTP method for the request.

required_scopes: set[AuthScope]

Required authorization scopes for the request.

class UnfollowArtistsOrUsersRequestBody(*, item_ids: Annotated[Sequence[str] | None, MaxLen(max_length=50)] = None)

Bases: RequestBodyJsonModel

Body for the Unfollow Artists or Users request model.

item_ids: Annotated[Sequence[str] | None, Field(max_length=50, serialization_alias='ids')]

A sequence of Spotify IDs for the artists or users to unfollow.

class UnfollowArtistsOrUsersRequestParams(*, item_type: SpotifyItemType, item_ids: Annotated[Sequence[str] | None, MaxLen(max_length=50), PlainSerializer(func=sequence_to_comma_separated_str, return_type=str, when_used=always)] = None)

Bases: BaseModel

Parameters for the Unfollow Artists or Users request model.

classmethod validate_type_param(value: SpotifyItemType) → SpotifyItemType

Validate that the type parameter is either ‘artist’ or ‘user’.

Parameters:

value – The SpotifyItemType value to validate.

Returns:

The validated SpotifyItemType value.

item_ids: Annotated[Sequence[str] | None, Field(max_length=50, serialization_alias='ids'), PlainSerializer(sequence_to_comma_separated_str, return_type=str)]

A sequence of Spotify IDs for the artists or users to unfollow.

item_type: SpotifyItemType

The type of the items to unfollow.

class UnfollowPlaylistRequest(*, required_scopes: set[AuthScope] = {AuthScope.PLAYLIST_MODIFY_PRIVATE, AuthScope.PLAYLIST_MODIFY_PUBLIC}, url: HttpUrl | None = None, endpoint: str | None = None, method_type: HTTPMethod = <HTTPMethod.DELETE>, headers: RequestHeadersModel = <factory>, params: UnfollowPlaylistRequestParams | None = None, body: None = None)

Bases: RequestModel[UnfollowPlaylistRequestParams, NoneType]

Request model for Unfollow Playlist endpoint.

classmethod build(*, playlist_id: SpotifyItemID) → UnfollowPlaylistRequest

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:

playlist_id – The Spotify ID of the playlist to unfollow.

Returns:

Validated Request object.

method_type: HTTPMethod

HTTP method for the request.

required_scopes: set[AuthScope]

Required authorization scopes for the request.

class UnfollowPlaylistRequestParams(*, playlist_id: SpotifyItemID)

Bases: BaseModel

Parameters for the Unfollow Playlist request model.

playlist_id: SpotifyItemID

The Spotify ID of the playlist to unfollow.

Response models

class GetFollowedArtistsResponse(*, artists: PagedResultWithCursorsModel[ArtistModel])

Bases: BaseModel

Response model for Get Followed Artists endpoint.

artists: PagedResultWithCursorsModel[ArtistModel]

List of artists.