Tracks Endpoint Reference

Functions

async check_user_saved_tracks(client: SpotanticClient, *, track_ids: Sequence[SpotifyItemID]) → APICallModel[CheckUserSavedTracksRequest, JsonAPIResponse, dict[SpotifyItemID, bool]]

Check if one or more tracks 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.

  • track_ids – A list of the Spotify IDs for the tracks.

Returns:

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

async get_several_tracks(client: SpotanticClient, *, track_ids: Sequence[SpotifyItemID], market: SpotifyMarketID | None = None) → APICallModel[GetSeveralTracksRequest, JsonAPIResponse, list[TrackModel]]

Get Spotify catalog information for multiple tracks 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.

  • track_ids – A list of the Spotify IDs for the tracks.

  • 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_track(client: SpotanticClient, *, track_id: SpotifyItemID, market: SpotifyMarketID | None = None) → APICallModel[GetTrackRequest, JsonAPIResponse, TrackModel]

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

Parameters:

  • client – SpotanticClient instance.

  • track_id – The Spotify ID for the track.

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

Get a list of the songs 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_tracks(client: SpotanticClient, *, track_ids: Sequence[SpotifyItemID]) → APICallModel[RemoveUserSavedTracksRequest, RawAPIResponse, NoneType]

Remove one or more tracks 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.

  • track_ids – A list of the Spotify IDs for the tracks to be removed.

Returns:

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

async save_tracks_for_current_user(client: SpotanticClient, *, track_ids: Sequence[SpotifyItemID] | None = None, timestamped_track_ids: dict[SpotifyItemID, datetime] | None = None) → APICallModel[SaveTracksForCurrentUserRequest, RawAPIResponse, NoneType]

Save one or more tracks 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.

  • track_ids – A list of the Spotify IDs for the tracks to be saved.

  • timestamped_track_ids – A dictionary mapping Spotify track IDs to the datetime they were added. This allows you to specify when tracks were added to maintain a specific chronological order in the user’s library.

Returns:

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

Request models

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

Bases: RequestModel[CheckUserSavedTracksRequestParams, NoneType]

Request model for Check User Saved Tracks endpoint.

classmethod build(*, track_ids: Sequence[SpotifyItemID]) → CheckUserSavedTracksRequest

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:

track_ids – A list of the Spotify IDs for the tracks.

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 CheckUserSavedTracksRequestParams(*, track_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 Tracks request.

track_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 tracks.

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

Bases: RequestModel[GetSeveralTracksRequestParams, NoneType]

Request model for Get Several Tracks endpoint.

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

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:

  • track_ids – A list of the Spotify IDs for the tracks.

  • 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 GetSeveralTracksRequestParams(*, track_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 Tracks request.

market: SpotifyMarketID | None

An ISO 3166-1 alpha-2 country code.

track_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 tracks.

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

Bases: RequestModel[GetTrackRequestParams, NoneType]

Request model for Get Track endpoint.

classmethod build(*, track_id: SpotifyItemID, market: SpotifyMarketID | None = None) → GetTrackRequest

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:

  • track_id – The Spotify ID for the track.

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

Returns:

Validated Request object.

method_type: HTTPMethod

HTTP method for the request.

class GetTrackRequestParams(*, track_id: SpotifyItemID, market: SpotifyMarketID | None = None)

Bases: BaseModel

Params model for Get Track request.

market: SpotifyMarketID | None

An ISO 3166-1 alpha-2 country code.

track_id: SpotifyItemID

The Spotify ID for the track.

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

Bases: RequestModel[GetUserSavedTracksRequestParams, NoneType]

Request model for Get User Saved Tracks endpoint.

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

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

Bases: BaseModel

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

Bases: RequestModel[RemoveUserSavedTracksRequestParams, NoneType]

Request model for Remove User Saved Tracks endpoint.

classmethod build(*, track_ids: Sequence[SpotifyItemID]) → RemoveUserSavedTracksRequest

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:

track_ids – A list of the Spotify IDs for the tracks.

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 RemoveUserSavedTracksRequestParams(*, track_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 Tracks request.

track_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 tracks.

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

Bases: RequestModel[NoneType, SaveTracksForCurrentUserRequestBody]

Request model for Save Tracks For Current User endpoint.

classmethod build(*, track_ids: Sequence[SpotifyItemID] | None = None, timestamped_ids: dict[SpotifyItemID, datetime] | None = None) → SaveTracksForCurrentUserRequest

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:

  • track_ids – A list of the Spotify IDs for the tracks.

  • timestamped_ids – A dictionary mapping Spotify track IDs to their added timestamps.

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 SaveTracksForCurrentUserRequestBody(*, track_ids: Annotated[Sequence[SpotifyItemID] | None, MaxLen(max_length=50)] = None, timestamped_ids: Sequence[TimestampTrackIDModel] | None = None)

Bases: RequestBodyJsonModel

Body model for Save Tracks For Current User request.

check_either_field() → SaveTracksForCurrentUserRequestBody

Validates that either track_ids or timestamped_ids is provided.

Parameters:

model – The model instance to validate.

Returns:

The validated model instance.

Raises:

ValueError – If neither of the fields is provided.

timestamped_ids: Sequence[TimestampTrackIDModel] | None

A list of track IDs with timestamps.

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

A list of the Spotify IDs for the tracks.

Response models

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

Bases: BaseModel

Response model for Get Several Tracks endpoint.

tracks: list[TrackModel]

List of tracks.