Artists Endpoint Reference

Functions

async get_artist(client: SpotanticClient, *, artist_id: SpotifyItemID) → APICallModel[GetArtistRequest, JsonAPIResponse, ArtistModel]

Get Spotify catalog information for a single artist identified by their unique Spotify ID.

Parameters:

  • client – SpotanticClient instance.

  • artist_id – The Spotify ID for the artist.

Returns:

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

async get_artist_albums(client: SpotanticClient, *, artist_id: SpotifyItemID, limit: int = 20, offset: int = 0, market: SpotifyMarketID | None = None, include_groups: Sequence[AlbumTypes] | None = None) → APICallModel[GetArtistAlbumsRequest, JsonAPIResponse, PagedResultModel[SimplifiedAlbumModel]]

Get Spotify catalog information about an artist’s albums.

Parameters:

  • client – SpotanticClient instance.

  • artist_id – The Spotify ID for the artist.

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

  • include_groups – A list of keywords that will be used to filter the response. If not supplied, all album types will be returned.

Returns:

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

async get_artist_top_tracks(client: SpotanticClient, *, artist_id: SpotifyItemID, market: SpotifyMarketID | None = None) → APICallModel[GetArtistTopTracksRequest, JsonAPIResponse, list[TrackModel]]

Get Spotify catalog information about an artist’s top tracks by country.

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.

  • artist_id – The Spotify ID for the artist.

  • 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_artists(client: SpotanticClient, *, artist_ids: Sequence[SpotifyItemID]) → APICallModel[GetSeveralArtistsRequest, JsonAPIResponse, list[ArtistModel]]

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

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

Returns:

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

Request models

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

Bases: RequestModel[GetArtistAlbumsRequestParams, NoneType]

Request model for Get Artist Albums endpoint.

classmethod build(*, artist_id: SpotifyItemID, limit: int = 20, offset: int = 0, market: SpotifyMarketID | None = None, include_groups: Sequence[AlbumTypes] | None = None) → GetArtistAlbumsRequest

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:

  • artist_id – The Spotify ID for the artist.

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

  • include_groups – A list of keywords that will be used to filter the response.

Returns:

Validated Request object.

method_type: HTTPMethod

HTTP method for the request.

class GetArtistAlbumsRequestParams(*, artist_id: SpotifyItemID, limit: Annotated[int, Ge(ge=1), Le(le=50)], offset: int, include_groups: Annotated[Sequence[AlbumTypes] | None, PlainSerializer(func=sequence_to_comma_separated_str, return_type=str, when_used=always)] = None, market: SpotifyMarketID | None = None)

Bases: BaseModel

Params model for Get Artist Albums request.

artist_id: SpotifyItemID

The Spotify ID for the artist.

include_groups: Annotated[Sequence[AlbumTypes] | None, PlainSerializer(sequence_to_comma_separated_str, return_type=str)]

A list of keywords that will be used to filter the response.

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 GetArtistRequest(*, required_scopes: set[AuthScope] = <factory>, url: HttpUrl | None = None, endpoint: str | None = None, method_type: HTTPMethod = <HTTPMethod.GET>, headers: RequestHeadersModel = <factory>, params: GetArtistRequestParams | None = None, body: None = None)

Bases: RequestModel[GetArtistRequestParams, NoneType]

Request model for Get Artist endpoint.

classmethod build(*, artist_id: SpotifyItemID) → GetArtistRequest

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:

artist_id – The Spotify ID for the artist.

Returns:

Validated Request object.

method_type: HTTPMethod

HTTP method for the request.

class GetArtistRequestParams(*, artist_id: SpotifyItemID)

Bases: BaseModel

Params model for Get Artist request.

artist_id: SpotifyItemID

The Spotify ID for the artist.

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

Bases: RequestModel[GetArtistTopTracksRequestParams, NoneType]

Request model for Get Artist Top Tracks endpoint.

classmethod build(*, artist_id: SpotifyItemID, market: SpotifyMarketID | None = None) → GetArtistTopTracksRequest

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:

  • artist_id – The Spotify ID for the artist.

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

Returns:

Validated Request object.

method_type: HTTPMethod

HTTP method for the request.

class GetArtistTopTracksRequestParams(*, artist_id: SpotifyItemID, market: SpotifyMarketID | None = None)

Bases: BaseModel

Params model for Get Artist Top Tracks request.

artist_id: SpotifyItemID

The Spotify ID for the artist.

market: SpotifyMarketID | None

An ISO 3166-1 alpha-2 country code.

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

Bases: RequestModel[GetSeveralArtistsRequestParams, NoneType]

Request model for Get Several Artists endpoint.

classmethod build(*, artist_ids: Sequence[SpotifyItemID]) → GetSeveralArtistsRequest

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:

artist_ids – A list of Spotify artist IDs to retrieve.

Returns:

Validated Request object.

endpoint: str | None

Endpoint associated with the request.

method_type: HTTPMethod

HTTP method for the request.

class GetSeveralArtistsRequestParams(*, artist_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 Get Several Artists request.

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

A list of Spotify artist IDs to retrieve.

Response models

class GetArtistTopTracksResponse(*, tracks: list[TrackModel])

Bases: BaseModel

Response model for Get Artist Top Tracks endpoint.

tracks: list[TrackModel]

List of tracks.

class GetSeveralArtistsResponse(*, artists: list[ArtistModel])

Bases: BaseModel

Response model for Get Several Artists endpoint.

artists: list[ArtistModel]

List of artists.