PrivateAPI#

class minim.tidal.PrivateAPI(*, client_id: str = None, client_secret: str = None, flow: str = None, browser: bool = False, scopes: str | list[str] = 'r_usr', user_agent: str = None, access_token: str = None, refresh_token: str = None, expiry: datetime = None, overwrite: bool = False, save: bool = True)[source]#

Bases: object

Private TIDAL API client.

The private TIDAL API allows media (tracks, videos), collections (albums, playlists), and performers to be queried, and information about them to be retrieved. As there is no available official documentation for the private TIDAL API, its endpoints have been determined by watching HTTP network traffic.

Attention

As the private TIDAL API is not designed to be publicly accessible, this class can be disabled or removed at any time to ensure compliance with the TIDAL Developer Terms of Service.

While authentication is not necessary to search for and retrieve data from public content, it is required to access personal content and stream media (with an active TIDAL subscription). In the latter case, requests to the private TIDAL API endpoints must be accompanied by a valid user access token in the header.

Minim can obtain user access tokens via the authorization code with proof key for code exchange (PKCE) and device code flows. These OAuth 2.0 authorization flows require valid client credentials (client ID and client secret) to either be provided to this class’s constructor as keyword arguments or be stored as TIDAL_PRIVATE_CLIENT_ID and TIDAL_PRIVATE_CLIENT_SECRET in the operating system’s environment variables.

Hint

Client credentials can be extracted from the software you use to access TIDAL, including but not limited to the TIDAL Web Player and the Android, iOS, macOS, and Windows applications. Only the TIDAL Web Player and desktop application client credentials can be used without authorization.

If an existing access token is available, it and its accompanying information (refresh token and expiry time) can be provided to this class’s constructor as keyword arguments to bypass the access token retrieval process. It is recommended that all other authentication-related keyword arguments be specified so that a new access token can be obtained when the existing one expires.

Tip

The authorization flow and access token can be changed or updated at any time using set_flow() and set_access_token(), respectively.

Minim also stores and manages access tokens and their properties. When an access token is acquired, it is automatically saved to the Minim configuration file to be loaded on the next instantiation of this class. This behavior can be disabled if there are any security concerns, like if the computer being used is a shared device.

Parameters:

client_idstr, keyword-only, optional

Client ID. If it is not stored as TIDAL_PRIVATE_CLIENT_ID in the operating system’s environment variables or found in the Minim configuration file, it must be provided here.

client_secretstr, keyword-only, optional

Client secret. Required for the authorization code and device code flows. If it is not stored as TIDAL_PRIVATE_CLIENT_SECRET in the operating system’s environment variables or found in the Minim configuration file, it must be provided here.

flowstr, keyword-only, optional

Authorization flow. If not specified, no user authentication will be performed.

Valid values:

"pkce" for the authorization code with proof key for code exchange (PKCE) flow.
"device_code" for the device code flow.

browserbool, keyword-only, default: False

Determines whether a web browser is automatically opened for the authorization code with PKCE or device code flows. If False, users will have to manually open the authorization URL, and for the authorization code flow, provide the full callback URI via the terminal. For the authorization code with PKCE flow, the Playwright framework by Microsoft is used.

scopesstr or list, keyword-only, default: "r_usr"

Authorization scopes to request user access for in the OAuth 2.0 flows.

Valid values: "r_usr", "w_usr", and "w_sub" (device code flow only).

user_agentstr, keyword-only, optional

User agent information to send in the header of HTTP requests.

Note

If not specified, TIDAL may temporarily block your IP address if you are making requests too quickly.

access_tokenstr, keyword-only, optional

Access token. If provided here or found in the Minim configuration file, the authentication process is bypassed. In the former case, all other relevant keyword arguments should be specified to automatically refresh the access token when it expires.

refresh_tokenstr, keyword-only, optional

Refresh token accompanying access_token. If not provided, the user will be reauthenticated using the specified authorization flow when access_token expires.

expirydatetime.datetime or str, keyword-only, optional

Expiry time of access_token in the ISO 8601 format %Y-%m-%dT%H:%M:%SZ. If provided, the user will be reauthenticated using refresh_token (if available) or the specified authorization flow (if possible) when access_token expires.

overwritebool, keyword-only, default: False

Determines whether to overwrite an existing access token in the Minim configuration file.

savebool, keyword-only, default: True

Determines whether newly obtained access tokens and their associated properties are stored to the Minim configuration file.

Attributes:

API_URLstr: Base URL for the private TIDAL API.
AUTH_URLstr: URL for device code requests.
LOGIN_URLstr: URL for authorization code requests.
REDIRECT_URLstr: URL for authorization code callbacks.
RESOURCES_URLstr: URL for cover art and image requests.
TOKEN_URLstr: URL for access token requests.
WEB_URLstr: URL for the TIDAL Web Player.
sessionrequests.Session: Session used to send requests to the private TIDAL API.

Methods

`add_playlist_items`	Add items to a playlist owned by the current user.
`block_artist`	Block an artist from appearing in mixes and the radio.
`block_user`	Block a user.
`create_playlist`	Create a user playlist.
`create_playlist_folder`	Create a user playlist folder.
`delete_playlist`	Delete a playlist owned by the current user.
`delete_playlist_folder`	Delete a playlist folder owned by the current user.
`delete_playlist_item`	Delete an item from a playlist owned by the current user.
`favorite_albums`	Add albums to the current user's collection.
`favorite_artists`	Add artists to the current user's collection.
`favorite_mixes`	Add mixes to the current user's collection.
`favorite_playlists`	Add playlists to the current user's collection.
`favorite_tracks`	Add tracks to the current user's collection.
`favorite_videos`	Add videos to the current user's collection.
`follow_user`	Follow a user.
`get_album`	Get TIDAL catalog information for an album.
`get_album_credits`	Get credits for an album.
`get_album_items`	Get TIDAL catalog information for items (tracks and videos) in an album.
`get_album_page`	Get the TIDAL page for an album.
`get_album_review`	Get a review of or a synopsis for an album.
`get_artist`	Get TIDAL catalog information for an artist.
`get_artist_albums`	Get TIDAL catalog information for albums by an artist.
`get_artist_biography`	Get an artist's biographical information.
`get_artist_links`	Get links to websites associated with an artist.
`get_artist_mix_id`	Get the ID of a curated mix of tracks based on an artist's works.
`get_artist_page`	Get the TIDAL page for an artist.
`get_artist_radio`	Get TIDAL catalog information for tracks inspired by an artist's works.
`get_artist_top_tracks`	Get TIDAL catalog information for an artist's top tracks.
`get_artist_videos`	Get TIDAL catalog information for an artist's videos.
`get_blocked_artists`	Get TIDAL catalog information for the current user's blocked artists.
`get_blocked_users`	Get users blocked by the current user.
`get_collection_streams`	Get audio and video stream data for items (tracks and videos) in an album, mix, or playlist.
`get_country_code`	Get the country code based on the current IP address.
`get_favorite_albums`	Get TIDAL catalog information for albums in the current user's collection.
`get_favorite_artists`	Get TIDAL catalog information for artists in the current user's collection.
`get_favorite_ids`	Get TIDAL IDs or UUIDs of the albums, artists, playlists, tracks, and videos in the current user's collection.
`get_favorite_mixes`	Get TIDAL catalog information for or IDs of mixes in the current user's collection.
`get_favorite_tracks`	Get TIDAL catalog information for tracks in the current user's collection.
`get_favorite_videos`	Get TIDAL catalog information for videos in the current user's collection.
`get_image`	Get (animated) cover art or image for a TIDAL item.
`get_mix_items`	Get TIDAL catalog information for items (tracks and videos) in a mix.
`get_mix_page`	Get the TIDAL page for a mix.
`get_personal_playlist_folders`	Get TIDAL catalog information for a playlist folder (and optionally, playlists and other playlist folders in it) created by the current user.
`get_personal_playlists`	Get TIDAL catalog information for playlists created by the current user.
`get_playlist`	Get TIDAL catalog information for a playlist.
`get_playlist_etag`	Get the entity tag (ETag) for a playlist.
`get_playlist_items`	Get TIDAL catalog information for items (tracks and videos) in a playlist.
`get_playlist_recommendations`	Get TIDAL catalog information for recommended tracks based on a playlist's items.
`get_profile`	Get the current user's profile information.
`get_session`	Get information about the current private TIDAL API session.
`get_similar_albums`	Get TIDAL catalog information for albums similar to the specified album.
`get_similar_artists`	Get TIDAL catalog information for artists similar to a specified artist.
`get_track`	Get TIDAL catalog information for a track.
`get_track_composers`	Get the composers, lyricists, and/or songwriters of a track.
`get_track_contributors`	Get the contributors to a track and their roles.
`get_track_credits`	Get credits for a track.
`get_track_lyrics`	Get lyrics for a track.
`get_track_mix_id`	Get the curated mix of tracks based on a track.
`get_track_playback_info`	Get playback information for a track.
`get_track_recommendations`	Get TIDAL catalog information for a track's recommended tracks and videos.
`get_track_stream`	Get the audio stream data for a track.
`get_user_followers`	Get a TIDAL user's followers.
`get_user_following`	Get the people (artists, users, etc.) a TIDAL user follows.
`get_user_playlist`	Get TIDAL catalog information for a user playlist.
`get_user_playlists`	Get TIDAL catalog information for playlists created by a TIDAL user.
`get_user_profile`	Get a TIDAL user's profile information.
`get_video`	Get TIDAL catalog information for a video.
`get_video_page`	Get the TIDAL page for a video.
`get_video_playback_info`	Get playback information for a video.
`get_video_stream`	Get the video stream data for a music video.
`move_playlist`	Move a playlist in the current user's collection.
`move_playlist_item`	Move an item in a playlist owned by the current user.
`search`	Search for albums, artists, tracks, and videos.
`set_access_token`	Set the private TIDAL API access token.
`set_flow`	Set the authorization flow.
`set_playlist_privacy`	Set the privacy of a playlist owned by the current user.
`unblock_artist`	Unblock an artist from appearing in mixes and the radio.
`unblock_user`	Unblock a user.
`unfavorite_albums`	Remove albums from the current user's collection.
`unfavorite_artists`	Remove artists from the current user's collection.
`unfavorite_mixes`	Remove mixes from the current user's collection.
`unfavorite_playlist`	Remove a playlist from the current user's collection.
`unfavorite_tracks`	Remove tracks from the current user's collection.
`unfavorite_videos`	Remove videos from the current user's collection.
`unfollow_user`	Unfollow a user.
`update_playlist`	Update the title or description of a playlist owned by the current user.

set_access_token(access_token: str = None, *, refresh_token: str = None, expiry: str | datetime = None) → None[source]#

Set the private TIDAL API access token.

Parameters:

access_tokenstr, optional: Access token. If not provided, an access token is obtained using an OAuth 2.0 authorization flow or from the Spotify Web Player.
refresh_tokenstr, keyword-only, optional: Refresh token accompanying access_token.
expirystr or datetime.datetime, keyword-only, optional: Access token expiry timestamp in the ISO 8601 format %Y-%m-%dT%H:%M:%SZ. If provided, the user will be reauthenticated using the refresh token (if available) or the default authorization flow (if possible) when access_token expires.

set_flow(flow: str, client_id: str, *, client_secret: str = None, browser: bool = False, scopes: str | list[str] = '', save: bool = True) → None[source]#

Set the authorization flow.

Parameters:

flowstr

Authorization flow. If not specified, no user authentication will be performed.

Valid values:

"pkce" for the authorization code with proof key for code exchange (PKCE) flow.
"client_credentials" for the client credentials flow.

client_idstr

Client ID.

client_secretstr, keyword-only, optional

Client secret. Required for all OAuth 2.0 authorization flows.

browserbool, keyword-only, default: False

scopesstr or list, keyword-only, optional

Authorization scopes to request user access for in the OAuth 2.0 flows.

Valid values: "r_usr", "w_usr", and "w_sub" (device code flow only).

savebool, keyword-only, default: True

Determines whether to save the newly obtained access tokens and their associated properties to the Minim configuration file.

get_album(album_id: int | str, country_code: str = None) → dict[str, Any][source]#

Get TIDAL catalog information for an album.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

album_idint or str

TIDAL album ID.

Example: 251380836.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

Returns:

albumdict

TIDAL catalog information for an album.

Sample response

{
  "id": <int>,
  "title": <str>,
  "duration": <int>,
  "streamReady": <bool>,
  "adSupportedStreamReady": <bool>,
  "djReady": <bool>,
  "stemReady": <bool>,
  "streamStartDate": <str>,
  "allowStreaming": <bool>,
  "premiumStreamingOnly": <bool>,
  "numberOfTracks": <int>,
  "numberOfVideos": <int>,
  "numberOfVolumes": <int>,
  "releaseDate": <str>,
  "copyright": <str>,
  "type": "ALBUM",
  "version": <str>,
  "url": <str>,
  "cover": <str>,
  "vibrantColor": <str>,
  "videoCover": <str>,
  "explicit": <bool>,
  "upc": <str>,
  "popularity": <int>,
  "audioQuality": <str>,
  "audioModes": [<str>],
  "mediaMetadata": {
    "tags": [<str>]
  },
  "artist": {
    "id": <int>,
    "name": <str>,
    "type": <str>,
    "picture": <str>
  },
  "artists": [
    {
      "id": <int>,
      "name": <str>,
      "type": <str>,
      "picture": <str>
    }
  ]
}

get_album_items(album_id: int | str, country_code: str = None, *, limit: int = 100, offset: int = None, credits: bool = False) → dict[str, Any][source]#

Get TIDAL catalog information for items (tracks and videos) in an album.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

album_idint or str

TIDAL album ID.

Examples: 251380836.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

limitint, keyword-only, default: 100

Page size.

Example: 10.

offsetint, keyword-only, optional

Pagination offset (in number of items).

Example: 0.

creditsbool, keyword-only, default: False

Determines whether credits for each item is returned.

Returns:

itemsdict

A dictionary containing TIDAL catalog information for tracks and videos in the specified album and metadata for the returned results.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "item": {
        "id": <int>,
        "title": <str>,
        "duration": <int>,
        "replayGain": <float>,
        "peak": <float>,
        "allowStreaming": <bool>,
        "streamReady": <bool>,
        "adSupportedStreamReady": <bool>,
        "djReady": <bool>,
        "stemReady": <bool>,
        "streamStartDate": <str>,
        "premiumStreamingOnly": <bool>,
        "trackNumber": <int>,
        "volumeNumber": >int>,
        "version": <str>,
        "popularity": <int>,
        "copyright": <str>,
        "url": <str>,
        "isrc": <str>,
        "editable": <bool>,
        "explicit": <bool>,
        "audioQuality": <str>,
        "audioModes": [<str>],
        "mediaMetadata": {
          "tags": [<str>]
        },
        "artist": {
          "id": <int>,
          "name": <str>,
          "type": <str>,
          "picture": <str>
        },
        "artists": [
          {
            "id": <int>,
            "name": <str>,
            "type": <str>,
            "picture": <str>
          }
        ],
        "album": {
          "id": <int>,
          "title": <str>,
          "cover": <str>,
          "vibrantColor": <str>,
          "videoCover": <str>
        },
        "mixes": {
          "TRACK_MIX": <str>
        }
      },
      "type": "track"
    }
  ]
}

get_album_credits(album_id: int | str, country_code: str = None) → dict[str, Any][source]#

Get credits for an album.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

album_idint or str

TIDAL album ID.

Example: 251380836.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

Returns:

creditsdict

A dictionary containing TIDAL catalog information for the album contributors.

Sample response

[
  {
    "type": <str>,
    "contributors": [
      {
        "name": <str>
      }
    ]
  }
]

get_album_review(album_id: int | str, country_code: str = None) → dict[str, str][source]#

Get a review of or a synopsis for an album.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

album_idint or str

TIDAL album ID.

Example: 251380836.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

Returns:

reviewdict

A dictionary containing a review of or a synopsis for an album and its source.

Sample response

{
  "source": <str>,
  "lastUpdated": <str>,
  "text": <str>,
  "summary": <str>
}

get_similar_albums(album_id: int | str, country_code: str = None) → dict[str, Any][source]#

Get TIDAL catalog information for albums similar to the specified album.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

album_idint or str

TIDAL album ID.

Example: 251380836.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

Returns:

albumdict

TIDAL catalog information for an album.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "id": <int>,
      "title": <str>,
      "duration": <int>,
      "streamReady": <bool>,
      "adSupportedStreamReady": <bool>,
      "djReady": <bool>,
      "stemReady": <bool>,
      "streamStartDate": <str>,
      "allowStreaming": <bool>,
      "premiumStreamingOnly": <bool>,
      "numberOfTracks": <int>,
      "numberOfVideos": <int>,
      "numberOfVolumes": <int>,
      "releaseDate": <str>,
      "copyright": <str>,
      "type": "ALBUM",
      "version": <str>,
      "url": <str>,
      "cover": <str>,
      "vibrantColor": <str>,
      "videoCover": <str>,
      "explicit": <bool>,
      "upc": <str>,
      "popularity": <int>,
      "audioQuality": <str>,
      "audioModes": [<str>],
      "mediaMetadata": {
        "tags": [<str>]
      },
      "artist": {
        "id": <int>,
        "name": <str>,
        "type": <str>,
        "picture": <str>
      },
      "artists": [
        {
          "id": <int>,
          "name": <str>,
          "type": <str>,
          "picture": <str>
        }
      ]
    }
  ],
  "source": <str>
}

get_favorite_albums(country_code: str = None, *, limit: int = 50, offset: int = None, order: str = 'DATE', order_direction: str = 'DESC') → None[source]#

Get TIDAL catalog information for albums in the current user’s collection.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

limitint, keyword-only, default: 50

Page size.

Example: 10.

offsetint, keyword-only, optional

Pagination offset (in number of items).

Example: 0.

orderstr, keyword-only, default: "DATE"

Sorting order.

Valid values: "DATE" and "NAME".

order_directionstr, keyword-only, default: "DESC"

Sorting order direction.

Valid values: "DESC" and "ASC".

Returns:

albumsdict

A dictionary containing TIDAL catalog information for albums in the current user’s collection and metadata for the returned results.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "created": <str>,
      "item": {
        "id": <int>,
        "title": <str>,
        "duration": <int>,
        "streamReady": <bool>,
        "adSupportedStreamReady": <bool>,
        "djReady": <bool>,
        "stemReady": <bool>,
        "streamStartDate": <str>,
        "allowStreaming": <bool>,
        "premiumStreamingOnly": <bool>,
        "numberOfTracks": <int>,
        "numberOfVideos": <int>,
        "numberOfVolumes": <int>,
        "releaseDate": <str>,
        "copyright": <str>,
        "type": "ALBUM",
        "version": <str>,
        "url": <str>,
        "cover": <str>,
        "vibrantColor": <str>,
        "videoCover": <str>,
        "explicit": <bool>,
        "upc": <str>,
        "popularity": <int>,
        "audioQuality": <str>,
        "audioModes": [<str>],
        "mediaMetadata": {
          "tags": [<str>]
        },
        "artist": {
          "id": <int>,
          "name": <str>,
          "type": <str>,
          "picture": <str>
        },
        "artists": [
          {
            "id": <int>,
            "name": <str>,
            "type": <str>,
            "picture": <str>
          }
        ]
      }
    }
  ]
}

favorite_albums(album_ids: int | str | list[int | str], country_code: str = None, *, on_artifact_not_found: str = 'FAIL') → None[source]#

Add albums to the current user’s collection.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

album_idsint, str, or list

TIDAL album ID(s).

Examples: "251380836,275646830" or [251380836, 275646830].

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

on_artifact_not_foundstr, keyword-only, default: "FAIL"

Behavior when the item to be added does not exist.

Valid values: "FAIL" or "SKIP".

unfavorite_albums(album_ids: int | str | list[int | str]) → None[source]#

Remove albums from the current user’s collection.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

album_idsint, str, or list

TIDAL album ID(s).

Examples: "251380836,275646830" or [251380836, 275646830].

get_artist(artist_id: int | str, country_code: str = None) → dict[str, Any][source]#

Get TIDAL catalog information for an artist.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

artist_idint or str

TIDAL artist ID.

Example: 1566.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

Returns:

artistdict

TIDAL catalog information for an artist.

Sample response

{
  "id": <int>,
  "name": <str>,
  "artistTypes": [<str>],
  "url": <str>,
  "picture": <str>,
  "popularity": <int>,
  "artistRoles": [
    {
      "categoryId": <int>,
      "category": <str>
    }
  ],
  "mixes": {
    "ARTIST_MIX": <str>
  }
}

get_artist_albums(artist_id: int | str, country_code: str = None, *, filter: str = None, limit: int = 100, offset: int = None) → dict[str, Any][source]#

Get TIDAL catalog information for albums by an artist.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

artist_idint or str

TIDAL artist ID.

Example: 1566.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

filterstr, keyword-only, optional

Subset of albums to retrieve.

Valid values: "EPSANDSINGLES" and "COMPILATIONS".

limitint, keyword-only, default: 100

Page size.

Example: 10.

offsetint, keyword-only, optional

Pagination offset (in number of items).

Example: 0.

Returns:

albumsdict

A dictionary containing TIDAL catalog information for albums by the specified artist and metadata for the returned results.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "id": <int>,
      "title": <str>,
      "duration": <int>,
      "streamReady": <bool>,
      "adSupportedStreamReady": <bool>,
      "djReady": <bool>,
      "stemReady": <bool>,
      "streamStartDate": <str>,
      "allowStreaming": <bool>,
      "premiumStreamingOnly": <bool>,
      "numberOfTracks": <int>,
      "numberOfVideos": <int>,
      "numberOfVolumes": <int>,
      "releaseDate": <str>,
      "copyright": <str>,
      "type": "ALBUM",
      "version": <str>,
      "url": <str>,
      "cover": <str>,
      "vibrantColor": <str>,
      "videoCover": <str>,
      "explicit": <bool>,
      "upc": <str>,
      "popularity": <int>,
      "audioQuality": <str>,
      "audioModes": [<str>],
      "mediaMetadata": {
        "tags": [<str>]
      },
      "artist": {
        "id": <int>,
        "name": <str>,
        "type": <str>,
        "picture": <str>
      },
      "artists": [
        {
          "id": <int>,
          "name": <str>,
          "type": <str>,
          "picture": <str>
        }
      ]
    }
  ]
}

get_artist_top_tracks(artist_id: int | str, country_code: str = None, *, limit: int = 100, offset: int = None) → dict[str, Any][source]#

Get TIDAL catalog information for an artist’s top tracks.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

artist_idint or str

TIDAL artist ID.

Example: 1566.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

limitint, keyword-only, default: 100

Page size.

Example: 10.

offsetint, keyword-only, optional

Pagination offset (in number of items).

Example: 0.

Returns:

tracksdict

A dictionary containing TIDAL catalog information for the artist’s top tracks and metadata for the returned results.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "id": <int>,
      "title": <str>,
      "duration": <int>,
      "replayGain": <float>,
      "peak": <float>,
      "allowStreaming": <bool>,
      "streamReady": <bool>,
      "adSupportedStreamReady": <bool>,
      "djReady": <bool>,
      "stemReady": <bool>,
      "streamStartDate": <str>,
      "premiumStreamingOnly": <bool>,
      "trackNumber": <int>,
      "volumeNumber": <int>,
      "version": <str>,
      "popularity": <int>,
      "copyright": <str>,
      "url": <str>,
      "isrc": <str>,
      "editable": <bool>,
      "explicit": <bool>,
      "audioQuality": <str>,
      "audioModes": [<str>],
      "mediaMetadata": {
        "tags": [<str>]
      },
      "artist": {
        "id": <int>,
        "name": <str>,
        "type": <str>,
        "picture": <str>
      },
      "artists": [
        {
          "id": <int>,
          "name": <str>,
          "type": <str>,
          "picture": <str>
        }
      ],
      "album": {
        "id": <int>,
        "title": <str>,
        "cover": <str>,
        "vibrantColor": <str>,
        "videoCover": <str>
      },
      "mixes": {
        "TRACK_MIX": <str>
      }
    }
  ]
}

get_artist_videos(artist_id: int | str, country_code: str = None, *, limit: int = 100, offset: int = None) → dict[str, Any][source]#

Get TIDAL catalog information for an artist’s videos.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

artist_idint or str

TIDAL artist ID.

Example: 1566.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

limitint, keyword-only, default: 100

Page size.

Example: 10.

offsetint, keyword-only, optional

Pagination offset (in number of items).

Example: 0.

Returns:

videosdict

A dictionary containing TIDAL catalog information for the artist’s videos and metadata for the returned results.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "id": <int>,
      "title": <str>,
      "volumeNumber": <int>,
      "trackNumber": <int>,
      "releaseDate": <str>,
      "imagePath": <str>,
      "imageId": <str>,
      "vibrantColor": <str>,
      "duration": <int>,
      "quality": <str>,
      "streamReady": <bool>,
      "adSupportedStreamReady": <bool>,
      "djReady": <bool>,
      "stemReady": <bool>,
      "streamStartDate": <str>,
      "allowStreaming": <bool>,
      "explicit": <bool>,
      "popularity": <int>,
      "type": "Music Video",
      "adsUrl": <str>,
      "adsPrePaywallOnly": <bool>,
      "artist": {
        "id": <int>,
        "name": <str>,
        "type": <str>,
        "picture": <str>
      },
      "artists": [
        {
          "id": <int>,
          "name": <str>,
          "type": <str>,
          "picture": <str>
        }
      ],
      "album": <dict>
    }
  ]
}

get_artist_mix_id(artist_id: int | str, country_code: str = None) → str[source]#

Get the ID of a curated mix of tracks based on an artist’s works.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

artist_idint or str

TIDAL artist ID.

Example: 1566.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

Returns:

mix_idstr

TIDAL mix ID.

Example: "000ec0b01da1ddd752ec5dee553d48".

get_artist_radio(artist_id: int | str, country_code: str = None, *, limit: int = None, offset: int = None) → dict[str, Any][source]#

Get TIDAL catalog information for tracks inspired by an artist’s works.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Note

This method is functionally identical to first getting the artist mix ID using get_artist_mix_id() and then retrieving TIDAL catalog information for the items in the mix using get_mix_items().

Parameters:

artist_idint or str

TIDAL artist ID.

Example: 1566.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

limitint, keyword-only, optional

Page size.

Default: 100.

offsetint, keyword-only, optional

Pagination offset (in number of items).

Example: 0.

Returns:

tracksdict

A dictionary containing TIDAL catalog information for tracks inspired by an artist’s works and metadata for the returned results.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "id": <int>,
      "title": <str>,
      "duration": <int>,
      "replayGain": <float>,
      "peak": <float>,
      "allowStreaming": <bool>,
      "streamReady": <bool>,
      "adSupportedStreamReady": <bool>,
      "djReady": <bool>,
      "stemReady": <bool>,
      "streamStartDate": <str>,
      "premiumStreamingOnly": <bool>,
      "trackNumber": <int>,
      "volumeNumber": <int>,
      "version": <str>,
      "popularity": <int>,
      "copyright": <str>,
      "url": <str>,
      "isrc": <str>,
      "editable": <bool>,
      "explicit": <bool>,
      "audioQuality": <str>,
      "audioModes": [<str>],
      "mediaMetadata": {
        "tags": [<str>]
      },
      "artist": {
        "id": <int>,
        "name": <str>,
        "type": <str>,
        "picture": <str>
      },
      "artists": [
        {
          "id": <int>,
          "name": <str>,
          "type": <str>,
          "picture": <str>
        }
      ],
      "album": {
        "id": <int>,
        "title": <str>,
        "cover": <str>,
        "vibrantColor": <str>,
        "videoCover": <str>
      },
      "mixes": {
        "TRACK_MIX": <str>
      }
    }
  ]
}

get_artist_biography(artist_id: int | str, country_code: str = None) → dict[str, str][source]#

Get an artist’s biographical information.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

artist_idint or str

TIDAL artist ID.

Example: 1566.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

Returns:

biographydict

A dictionary containing an artist’s biographical information and its source.

Sample response

{
  "source": <str>,
  "lastUpdated": <str>,
  "text": <str>,
  "summary": <str>
}

get_artist_links(artist_id: int | str, country_code: str = None, *, limit: int = None, offset: int = None) → dict[str, Any][source]#

Get links to websites associated with an artist.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

artist_idint or str

TIDAL artist ID.

Example: 1566.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

limitint, keyword-only, optional

Page size.

Example: 10.

offsetint, keyword-only, optional

Pagination offset (in number of items).

Example: 0.

Returns:

linksdict

A dictionary containing the artist’s links and metadata for the returned results.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "url": <str>,
      "siteName": <str>
    }
  ],
  "source": <str>
}

get_similar_artists(artist_id: str, country_code: str = None, *, limit: int = None, offset: int = None) → dict[str, Any][source]#

Get TIDAL catalog information for artists similar to a specified artist.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

artist_idint or str

TIDAL artist ID.

Example: 1566.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

limitint, keyword-only, default: 100

Page size.

Example: 10.

offsetint, keyword-only, optional

Pagination offset (in number of items).

Example: 0.

Returns:

artistsdict

A dictionary containing TIDAL catalog information for artists similar to the specified artist and metadata for the returned results.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "id": <int>,
      "name": <str>,
      "type": None,
      "artistTypes": [<str>],
      "url": <str>,
      "picture": <str>,
      "popularity": <int>,
      "banner": <str>,
      "artistRoles": <list>,
      "mixes": <dict>,
      "relationType": "SIMILAR_ARTIST"
    }
  ],
  "source": "TIDAL"
}

get_favorite_artists(country_code: str = None, *, limit: int = 50, offset: int = None, order: str = 'DATE', order_direction: str = 'DESC') → None[source]#

Get TIDAL catalog information for artists in the current user’s collection.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

limitint, keyword-only, default: 50

Page size.

Example: 10.

offsetint, keyword-only, optional

Pagination offset (in number of items).

Example: 0.

orderstr, keyword-only, default: "DATE"

Sorting order.

Valid values: "DATE" and "NAME".

order_directionstr, keyword-only, default: "DESC"

Sorting order direction.

Valid values: "DESC" and "ASC".

Returns:

artistsdict

A dictionary containing TIDAL catalog information for artists in the current user’s collection and metadata for the returned results.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "created": <str>,
      "item": {
        "id": <int>,
        "name": <str>,
        "artistTypes": [<str>],
        "url": <str>,
        "picture": <str>,
        "popularity": <int>,
        "artistRoles": [
          {
            "categoryId": <int>,
            "category": <str>
          }
        ],
        "mixes": {
          "ARTIST_MIX": <str>
        }
      }
    }
  ]
}

favorite_artists(artist_ids: int | str | list[int | str], country_code: str = None, *, on_artifact_not_found: str = 'FAIL') → None[source]#

Add artists to the current user’s collection.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

artist_idsint, str, or list

TIDAL artist ID(s).

Examples: "1566,7804" or [1566, 7804].

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

on_artifact_not_foundstr, keyword-only, default: "FAIL"

Behavior when the item to be added does not exist.

Valid values: "FAIL" or "SKIP".

unfavorite_artists(artist_ids: int | str | list[int | str]) → None[source]#

Remove artists from the current user’s collection.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

artist_idsint, str, or list

TIDAL artist ID(s).

Examples: "1566,7804" or [1566, 7804].

get_blocked_artists(*, limit: int = 50, offset: int = None) → dict[str, Any][source]#

Get TIDAL catalog information for the current user’s blocked artists.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

limitint, keyword-only, default: 50

Page size.

Example: 10.

offsetint, keyword-only, optional

Pagination offset (in number of items).

Example: 0.

Returns:

artistsdict

A dictionary containing TIDAL catalog information for the the current user’s blocked artists and metadata for the returned results.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "item": {
        "id": <int>,
        "name": <str>,
        "type": <str>,
        "artistTypes": [<str>],
        "url": <str>,
        "picture": <str>,
        "popularity": <int>,
        "banner": <str>,
        "artistRoles": [
          {
            "categoryId": <int>,
            "category": <str>
          }
        ],
        "mixes": {
          "ARTIST_MIX": <str>
        }
      },
      "created": <str>,
      "type": "ARTIST"
    }
  ]
}

block_artist(artist_id: int | str) → None[source]#

Block an artist from appearing in mixes and the radio.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

artist_idint or str

TIDAL artist ID.

Example: 1566.

unblock_artist(artist_id: int | str) → None[source]#

Unblock an artist from appearing in mixes and the radio.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

artist_idint or str

TIDAL artist ID.

Example: 1566.

get_country_code() → str[source]#

Get the country code based on the current IP address.

Returns:

countrystr, keyword-only, optional

ISO 3166-1 alpha-2 country code.

Example: "US".

get_image(uuid: str, type: str = None, animated: bool = False, *, width: int = None, height: int = None, filename: str | Path = None) → bytes[source]#

Get (animated) cover art or image for a TIDAL item.

Note

This method is provided for convenience and is not a private TIDAL API endpoint.

Parameters:

uuidstr

Image UUID.

Example: "d3c4372b-a652-40e0-bdb1-fc8d032708f6".

typestr

Item type.

Valid values: "artist", "album", "playlist", "track", "userProfile", and "video".

animatedbool, default: False

Specifies whether the image is animated.

widthint, keyword-only, optional

Valid image width for the item type. If not specified, the default size for the item type is used.

heightint, keyword-only, optional

Valid image height for the item type. If not specified, the default size for the item type is used.

filenamestr or pathlib.Path, keyword-only, optional

Filename with the .jpg or .mp4 extension. If specified, the image is saved to a file instead.

Returns:

imagebytes: Image data. If save=True, the stream data is saved to an image or video file and its filename is returned instead.

get_mix_items(mix_id: str, country_code: str = None) → dict[str, Any][source]#

Get TIDAL catalog information for items (tracks and videos) in a mix.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

mix_idstr

TIDAL mix ID.

Example: "000ec0b01da1ddd752ec5dee553d48".

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

Returns:

itemsdict

A dictionary containing TIDAL catalog information for tracks and videos in the specified mix and metadata for the returned results.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "item": {
        "id": <int>,
        "title": <str>,
        "duration": <int>,
        "replayGain": <float>,
        "peak": <float>,
        "allowStreaming": <bool>,
        "streamReady": <bool>,
        "adSupportedStreamReady": <bool>,
        "djReady": <bool>,
        "stemReady": <bool>,
        "streamStartDate": <str>,
        "premiumStreamingOnly": <bool>,
        "trackNumber": <int>,
        "volumeNumber": >int>,
        "version": <str>,
        "popularity": <int>,
        "copyright": <str>,
        "url": <str>,
        "isrc": <str>,
        "editable": <bool>,
        "explicit": <bool>,
        "audioQuality": <str>,
        "audioModes": [<str>],
        "mediaMetadata": {
          "tags": [<str>]
        },
        "artist": {
          "id": <int>,
          "name": <str>,
          "type": <str>,
          "picture": <str>
        },
        "artists": [
          {
            "id": <int>,
            "name": <str>,
            "type": <str>,
            "picture": <str>
          }
        ],
        "album": {
          "id": <int>,
          "title": <str>,
          "cover": <str>,
          "vibrantColor": <str>,
          "videoCover": <str>
        },
        "mixes": {
          "TRACK_MIX": <str>
        }
      },
      "type": "track"
    }
  ]
}

get_favorite_mixes(*, ids: bool = False, limit: int = 50, cursor: str = None) → dict[str, Any][source]#

Get TIDAL catalog information for or IDs of mixes in the current user’s collection.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

idsbool, keyword-only, default: False

Determine whether TIDAL catalog information about the mixes (False) or the mix IDs (True) are returned.

limitint, keyword-only, default: 50

Page size.

Example: 10.

cursorstr, keyword-only, optional

Cursor position of the last item in previous search results. Use with limit to get the next page of search results.

Returns:

mixesdict

A dictionary containing the TIDAL catalog information for or IDs of the mixes in the current user’s collection and the cursor position.

Sample response

{
  "items": [
    {
      "dateAdded": <str>,
      "title": <str>,
      "id": <str>,
      "mixType": <str>,
      "updated": <str>,
      "subTitleTextInfo": {
        "text": <str>,
        "color": <str>
      },
      "images": {
        "SMALL": {
          "width": <int>,
          "height": <int>,
          "url": <str>
        },
        "MEDIUM": {
          "width": <int>,
          "height": <int>,
          "url": <str>
        },
        "LARGE": {
          "width": <int>,
          "height": <int>,
          "url": <str>
        },
      },
      "detailImages": {
        "SMALL": {
          "width": <int>,
          "height": <int>,
          "url": <str>
        },
        "MEDIUM": {
          "width": <int>,
          "height": <int>,
          "url": <str>
        },
        "LARGE": {
          "width": <int>,
          "height": <int>,
          "url": <str>
        }
      },
      "master": <bool>,
      "subTitle": <str>,
      "titleTextInfo": {
        "text": <str>,
        "color": <str>
      }
    }
  ],
  "cursor": <str>,
  "lastModifiedAt": <str>
}

favorite_mixes(mix_ids: str | list[str], *, on_artifact_not_found: str = 'FAIL') → None[source]#

Add mixes to the current user’s collection.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

mix_idsstr or list

TIDAL mix ID(s).

Examples: "000ec0b01da1ddd752ec5dee553d48, 000dd748ceabd5508947c6a5d3880a" or ["000ec0b01da1ddd752ec5dee553d48", "000dd748ceabd5508947c6a5d3880a"]

on_artifact_not_foundstr, keyword-only, default: "FAIL"

Behavior when the item to be added does not exist.

Valid values: "FAIL" or "SKIP".

unfavorite_mixes(mix_ids: str | list[str]) → None[source]#

Remove mixes from the current user’s collection.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

mix_idsstr or list

TIDAL mix ID(s).

Examples: "000ec0b01da1ddd752ec5dee553d48, 000dd748ceabd5508947c6a5d3880a" or ["000ec0b01da1ddd752ec5dee553d48", "000dd748ceabd5508947c6a5d3880a"]

get_album_page(album_id: int | str, country_code: str = None, *, device_type: str = 'BROWSER') → dict[str, Any][source]#

Get the TIDAL page for an album.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

album_idint or str

TIDAL album ID.

Example: 251380836.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

device_typestr, keyword-only, default: "BROWSER"

Device type.

Valid values:

"BROWSER" for a web browser.
"DESKTOP" for the desktop TIDAL application.
"PHONE" for the mobile TIDAL application.
"TV" for the smart TV TIDAL application.

Returns:

pagedict: A dictionary containing the page ID, title, and submodules.

get_artist_page(artist_id: int | str, country_code: str = None, *, device_type: str = 'BROWSER') → dict[str, Any][source]#

Get the TIDAL page for an artist.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

artist_idint or str

TIDAL artist ID.

Example: 1566.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

device_typestr, keyword-only, default: "BROWSER"

Device type.

Valid values:

"BROWSER" for a web browser.
"DESKTOP" for the desktop TIDAL application.
"PHONE" for the mobile TIDAL application.
"TV" for the smart TV TIDAL application.

Returns:

pagedict: A dictionary containing the page ID, title, and submodules.

get_mix_page(mix_id: str, country_code: str = None, *, device_type: str = 'BROWSER') → dict[str, Any][source]#

Get the TIDAL page for a mix.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

mix_idstr

TIDAL mix ID.

Example: "000ec0b01da1ddd752ec5dee553d48".

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

device_typestr, keyword-only, default: "BROWSER"

Device type.

Valid values:

"BROWSER" for a web browser.
"DESKTOP" for the desktop TIDAL application.
"PHONE" for the mobile TIDAL application.
"TV" for the smart TV TIDAL application.

Returns:

pagedict: A dictionary containing the page ID, title, and submodules.

get_video_page(video_id: int | str, country_code: str = None, *, device_type: str = 'BROWSER') → dict[str, Any][source]#

Get the TIDAL page for a video.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

video_idint or str

TIDAL video ID.

Example: 75623239.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

device_typestr, keyword-only, default: "BROWSER"

Device type.

Valid values:

"BROWSER" for a web browser.
"DESKTOP" for the desktop TIDAL application.
"PHONE" for the mobile TIDAL application.
"TV" for the smart TV TIDAL application.

Returns:

pagedict: A dictionary containing the page ID, title, and submodules.

get_playlist(playlist_uuid: str, country_code: str = None) → dict[str, Any][source]#

Get TIDAL catalog information for a playlist.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

playlist_uuidstr

TIDAL playlist UUID.

Example: "36ea71a8-445e-41a4-82ab-6628c581535d".

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

Returns:

playlistdict

TIDAL catalog information for a playlist.

Sample response

{
  "uuid": <str>,
  "title": <str>,
  "numberOfTracks": <int>,
  "numberOfVideos": <int>,
  "creator": {
    "id": <int>
  },
  "description": <str>,
  "duration": <int>,
  "lastUpdated": <str>,
  "created": <str>,
  "type": <str>,
  "publicPlaylist": <bool>,
  "url": <str>,
  "image": <str>,
  "popularity": <int>,
  "squareImage": <str>,
  "promotedArtists": [
    {
      "id": <int>,
      "name": <str>,
      "type": <str>,
      "picture": <str>,
    }
  ],
  "lastItemAddedAt": <str>
}

get_playlist_etag(playlist_uuid: str, country_code: str = None) → str[source]#

Get the entity tag (ETag) for a playlist.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Note

This method is provided for convenience and is not a private TIDAL API endpoint.

Parameters:

playlist_uuidstr

TIDAL playlist UUID.

Example: "36ea71a8-445e-41a4-82ab-6628c581535d".

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

Returns:

etagstr

ETag for a playlist.

Example: "1698984074453".

get_playlist_items(playlist_uuid: str, country_code: str = None, *, limit: int = 100, offset: int = None) → dict[str, Any][source]#

Get TIDAL catalog information for items (tracks and videos) in a playlist.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

playlist_uuidstr

TIDAL playlist UUID.

Example: "36ea71a8-445e-41a4-82ab-6628c581535d".

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

limitint, keyword-only, default: 100

Page size.

Example: 10.

offsetint, keyword-only, optional

Pagination offset (in number of items).

Example: 0.

Returns:

itemsdict

A dictionary containing TIDAL catalog information for tracks and videos in the specified playlist and metadata for the returned results.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "item": {
        "id": <int>,
        "title": <str>,
        "duration": <int>,
        "replayGain": <float>,
        "peak": <float>,
        "allowStreaming": <bool>,
        "streamReady": <bool>,
        "adSupportedStreamReady": <bool>,
        "djReady": <bool>,
        "stemReady": <bool>,
        "streamStartDate": <str>,
        "premiumStreamingOnly": <bool>,
        "trackNumber": <int>,
        "volumeNumber": >int>,
        "version": <str>,
        "popularity": <int>,
        "copyright": <str>,
        "url": <str>,
        "isrc": <str>,
        "editable": <bool>,
        "explicit": <bool>,
        "audioQuality": <str>,
        "audioModes": [<str>],
        "mediaMetadata": {
          "tags": [<str>]
        },
        "artist": {
          "id": <int>,
          "name": <str>,
          "type": <str>,
          "picture": <str>
        },
        "artists": [
          {
            "id": <int>,
            "name": <str>,
            "type": <str>,
            "picture": <str>
          }
        ],
        "album": {
          "id": <int>,
          "title": <str>,
          "cover": <str>,
          "vibrantColor": <str>,
          "videoCover": <str>
        },
        "mixes": {
          "TRACK_MIX": <str>
        }
      },
      "type": "track"
    }
  ]
}

get_playlist_recommendations(playlist_uuid: str, country_code: str = None, *, limit: int = None, offset: int = None) → dict[str, Any][source]#

Get TIDAL catalog information for recommended tracks based on a playlist’s items.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

playlist_uuidstr

TIDAL playlist UUID.

Example: "36ea71a8-445e-41a4-82ab-6628c581535d".

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

limitint, keyword-only, optional

Page size.

Example: 10.

offsetint, keyword-only, optional

Pagination offset (in number of items).

Example: 0.

Returns:

itemsdict

A dictionary containing TIDAL catalog information for recommended tracks and videos and metadata for the returned results.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "item": {
        "id": <int>,
        "title": <str>,
        "duration": <int>,
        "replayGain": <float>,
        "peak": <float>,
        "allowStreaming": <bool>,
        "streamReady": <bool>,
        "adSupportedStreamReady": <bool>,
        "djReady": <bool>,
        "stemReady": <bool>,
        "streamStartDate": <str>,
        "premiumStreamingOnly": <bool>,
        "trackNumber": <int>,
        "volumeNumber": >int>,
        "version": <str>,
        "popularity": <int>,
        "copyright": <str>,
        "url": <str>,
        "isrc": <str>,
        "editable": <bool>,
        "explicit": <bool>,
        "audioQuality": <str>,
        "audioModes": [<str>],
        "mediaMetadata": {
          "tags": [<str>]
        },
        "artist": {
          "id": <int>,
          "name": <str>,
          "type": <str>,
          "picture": <str>
        },
        "artists": [
          {
            "id": <int>,
            "name": <str>,
            "type": <str>,
            "picture": <str>
          }
        ],
        "album": {
          "id": <int>,
          "title": <str>,
          "cover": <str>,
          "vibrantColor": <str>,
          "videoCover": <str>
        },
        "mixes": {
          "TRACK_MIX": <str>
        }
      },
      "type": "track"
    }
  ]
}

favorite_playlists(playlist_uuids: str | list[str], *, folder_id: str = 'root') → None[source]#

Add playlists to the current user’s collection.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

playlist_uuidsstr or list

TIDAL playlist UUID(s).

Example: ["36ea71a8-445e-41a4-82ab-6628c581535d", "4261748a-4287-4758-aaab-6d5be3e99e52"].

folder_idstr, keyword-only, default: "root"

ID of the folder to move the playlist into. To place a playlist directly under “My Playlists”, use folder_id="root".

move_playlist(playlist_uuid: str, folder_id: str) → None[source]#

Move a playlist in the current user’s collection.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

playlist_uuidstr

TIDAL playlist UUID.

Example: "36ea71a8-445e-41a4-82ab-6628c581535d".

folder_idstr

ID of the folder to move the playlist into. To place a playlist directly under “My Playlists”, use folder_id="root".

unfavorite_playlist(playlist_uuid: str) → None[source]#

Remove a playlist from the current user’s collection.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

playlist_uuidstr

TIDAL playlist UUID.

Example: "36ea71a8-445e-41a4-82ab-6628c581535d".

get_user_playlist(playlist_uuid: str) → dict[str, Any][source]#

Get TIDAL catalog information for a user playlist.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

playlist_uuidstr

TIDAL user playlist UUID.

Example: "e09ab9ce-2e87-41b8-b404-3cd712bf706e".

Returns:

playlistdict

TIDAL catalog information for a user playlist.

Sample response

{
  "playlist": {
    "uuid": <str>,
    "type": "USER",
    "creator": {
      "id": <int>,
      "name": <str>,
      "picture": <str>,
      "type": "USER"
    },
    "contentBehavior": <str>,
    "sharingLevel": <str>,
    "status": <str>,
    "source": <str>,
    "title": <str>,
    "description": <str>,
    "image": <str>,
    "squareImage": <str>,
    "url": <str>,
    "created": <str>,
    "lastUpdated": <str>,
    "lastItemAddedAt": <str>,
    "duration": <int>,
    "numberOfTracks": <int>,
    "numberOfVideos": <int>,
    "promotedArtists": [],
    "trn": <str>,
  },
  "followInfo": {
    "nrOfFollowers": <int>,
    "tidalResourceName": <str>,
    "followed": <bool>,
    "followType": "PLAYLIST"
  },
  "profile": {
    "userId": <int>,
    "name": <str>,
    "color": [<str>]
  }
}

get_user_playlists(user_id: int | str = None, *, limit: int = 50, cursor: str = None) → dict[str, Any][source]#

Get TIDAL catalog information for playlists created by a TIDAL user.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

user_idstr

TIDAL user ID. If not specified, the ID associated with the user account in the current session is used.

limitint, keyword-only, default: 50

Page size.

Example: 10.

cursorstr, keyword-only, optional

Cursor position of the last item in previous search results. Use with limit to get the next page of search results.

Returns:

playlistsdict

A dictionary containing the user’s playlists and the cursor position.

Sample response

{
  "items": [
    {
      "playlist": {
        "uuid": <str>,
        "type": "USER",
        "creator": {
          "id": <int>,
          "name": <str>,
          "picture": <str>,
          "type": "USER"
        },
        "contentBehavior": <str>,
        "sharingLevel": <str>,
        "status": <str>,
        "source": <str>,
        "title": <str>,
        "description": <str>,
        "image": <str>,
        "squareImage": <str>,
        "url": <str>,
        "created": <str>,
        "lastUpdated": <str>,
        "lastItemAddedAt": <str>,
        "duration": <int>,
        "numberOfTracks": <int>,
        "numberOfVideos": <int>,
        "promotedArtists": [],
        "trn": <str>,
      },
      "followInfo": {
        "nrOfFollowers": <int>,
        "tidalResourceName": <str>,
        "followed": <bool>,
        "followType": "PLAYLIST"
      },
      "profile": {
        "userId": <int>,
        "name": <str>,
        "color": [<str>]
      }
    }
  ],
  "cursor": <str>
}

get_personal_playlists(country_code: str = None, *, limit: int = 50, offset: int = None) → dict[str, Any][source]#

Get TIDAL catalog information for playlists created by the current user.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

limitint, keyword-only, default: 50

Page size.

Example: 10.

offsetint, keyword-only, optional

Pagination offset (in number of items).

Example: 0.

Returns:

playlistsdict

TIDAL catalog information for a user playlists created by the current user and metadata for the returned results.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "uuid": <str>",
      "title": <str>,
      "numberOfTracks": <int>,
      "numberOfVideos": <int>,
      "creator": {
        "id": <int>
      },
      "description": <str>,
      "duration": <int>,
      "lastUpdated": <str>,
      "created": <str>,
      "type": "USER",
      "publicPlaylist": <bool>,
      "url": <str>,
      "image": <str>,
      "popularity": <int>,
      "squareImage": <str>,
      "promotedArtists": [],
      "lastItemAddedAt": <str>
    }
  ]
}

create_playlist(name: str, *, description: str = None, folder_uuid: str = 'root', public: bool = None) → dict[str, Any][source]#

Create a user playlist.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

namestr: Playlist name.
descriptionstr, keyword-only, optional: Brief playlist description.
folder_uuidstr, keyword-only, default: "root": UUID of the folder the new playlist will be placed in. To place a playlist directly under “My Playlists”, use folder_id="root".
publicbool, keyword-only, optional: Determines whether the playlist is public (True) or private (False).

Returns:

playlistdict

TIDAL catalog information for the newly created playlist.

Sample response

{
  "trn": <str>,
  "itemType": "PLAYLIST",
  "addedAt": <str>,
  "lastModifiedAt": <str>,
  "name": <str>,
  "parent": <str>,
  "data": {
    "uuid": <str>,
    "type": "USER",
    "creator": {
      "id": <int>,
      "name": <str>,
      "picture": <str>,
      "type": "USER"
    },
    "contentBehavior": <str>,
    "sharingLevel": <str>,
    "status": "READY",
    "source": <str>,
    "title": <str>,
    "description": <str>,
    "image": <str>,
    "squareImage": <str>,
    "url": <str>,
    "created": <str>,
    "lastUpdated": <str>,
    "lastItemAddedAt": <str>,
    "duration": <int>,
    "numberOfTracks": <int>,
    "numberOfVideos": <int>,
    "promotedArtists": <list>,
    "trn": <str>,
    "itemType": "PLAYLIST"
  }
}

update_playlist(playlist_uuid: str, *, title: str = None, description: str = None) → None[source]#

Update the title or description of a playlist owned by the current user.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

playlist_uuidstr

TIDAL playlist UUID.

Example: "e09ab9ce-2e87-41b8-b404-3cd712bf706e".

titlestr, keyword-only, optional

New playlist title.

descriptionstr, keyword-only, optional

New playlist description.

set_playlist_privacy(playlist_uuid: str, public: bool) → None[source]#

Set the privacy of a playlist owned by the current user.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

playlist_uuidstr

TIDAL playlist UUID.

Example: "e09ab9ce-2e87-41b8-b404-3cd712bf706e".

publicbool

Determines whether the playlist is public (True) or private (False).

add_playlist_items(playlist_uuid: str, items: int | str | list[int | str] = None, *, from_playlist_uuid: str = None, on_duplicate: str = 'FAIL', on_artifact_not_found: str = 'FAIL') → None[source]#

Add items to a playlist owned by the current user.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

playlist_uuidstr

TIDAL playlist UUID.

Example: "e09ab9ce-2e87-41b8-b404-3cd712bf706e".

itemsint, str, or list, optional

Items to add to the playlist. If not specified, from_playlist_uuid must be provided.

Note

If both items and from_playlist_uuid are specified, only the items in items will be added to the playlist.

from_playlist_uuidstr, keyword-only, optional

TIDAL playlist from which to copy items.

on_duplicatestr, keyword-only, default: "FAIL"

Behavior when the item to be added is already in the playlist.

Valid values: "ADD", "SKIP", and "FAIL".

on_artifact_not_foundstr, keyword-only, default: "FAIL"

Behavior when the item to be added does not exist.

Valid values: "FAIL".

move_playlist_item(playlist_uuid: str, from_index: int | str, to_index: int | str) → None[source]#

Move an item in a playlist owned by the current user.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

playlist_uuidstr

TIDAL playlist UUID.

Example: "e09ab9ce-2e87-41b8-b404-3cd712bf706e".

from_indexint or str

Current item index.

to_indexint or str

Desired item index.

delete_playlist_item(playlist_uuid: str, index: int | str) → None[source]#

Delete an item from a playlist owned by the current user.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

playlist_uuidstr

TIDAL playlist UUID.

Example: "e09ab9ce-2e87-41b8-b404-3cd712bf706e".

indexint or str

Item index.

delete_playlist(playlist_uuid: str) → None[source]#

Delete a playlist owned by the current user.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

playlist_uuidstr

TIDAL playlist UUID.

Example: "e09ab9ce-2e87-41b8-b404-3cd712bf706e".

get_personal_playlist_folders(folder_uuid: str = None, *, flattened: bool = False, include_only: str = None, limit: int = 50, order: str = 'DATE', order_direction: str = 'DESC') → dict[str, Any][source]#

Get TIDAL catalog information for a playlist folder (and optionally, playlists and other playlist folders in it) created by the current user.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

folder_uuidstr, optional

UUID of the folder in which to look for playlists and other folders. If not specified, all folders and playlists in “My Playlists” are returned.

flattenedbool, keyword-only, default: False

Determines whether the results are flattened into a list.

include_onlystr, keyword-only, optional

Type of playlist-related item to return.

Valid values: "FAVORITE_PLAYLIST", "FOLDER", and "PLAYLIST".

limitint, keyword-only, default: 50

Page size.

Example: 10.

orderstr, keyword-only, default: "DATE"

Sorting order.

Valid values: "DATE", "DATE_UPDATED", and "NAME".

order_directionstr, keyword-only, default: "DESC"

Sorting order direction.

Valid values: "DESC" and "ASC".

Returns:

itemsdict

A dictionary containing playlist-related items and the total number of items available.

Sample response

{
  "lastModifiedAt": <str>,
  "items": [
    {
      "trn": <str>,
      "itemType": "FOLDER",
      "addedAt": <str>,
      "lastModifiedAt": <str>,
      "name": <str>,
      "parent": <str>,
      "data": {
        "trn": <str>,
        "name": <str>,
        "createdAt": <str>,
        "lastModifiedAt": <str>,
        "totalNumberOfItems": <int>,
        "id": <str>,
        "itemType": "FOLDER"
      }
    }
  ],
  "totalNumberOfItems": <int>,
  "cursor": <str>
}

create_playlist_folder(name: str, *, folder_uuid: str = 'root') → None[source]#

Create a user playlist folder.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

namestr: Playlist folder name.
folder_uuidstr, keyword-only, default: "root": UUID of the folder in which the new playlist folder should be created in. To create a folder directly under “My Playlists”, use folder_id="root".

delete_playlist_folder(folder_uuid: str) → None[source]#

Delete a playlist folder owned by the current user.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

folder_uuidstr

TIDAL playlist folder UUID.

Example: "92b3c1ea-245a-4e5a-a5a4-c215f7a65b9f".

search(query: str, country_code: str = None, *, type: str = None, limit: int = None, offset: int = None) → dict[str, Any][source]#

Search for albums, artists, tracks, and videos.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

querystr

Search query.

Example: "Beyoncé".

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

typestr, keyword-only, optional

Target search type. Searches for all types if not specified.

Valid values: "ALBUMS", "ARTISTS", "TRACKS", "VIDEOS".

limitint, keyword-only, optional

Page size.

Example: 10.

offsetint, keyword-only, optional

Pagination offset (in number of items).

Example: 0.

Returns:

resultsdict

A dictionary containing TIDAL catalog information for albums, artists, tracks, and videos matching the search query, and metadata for the returned results.

Sample response

{
  "artists": {
    "limit": <int>,
    "offset": <int>,
    "totalNumberOfItems": <int>,
    "items": [
      {
        "id": <int>,
        "name": <str>,
        "artistTypes": [<str>],
        "url": <str>,
        "picture": <str>,
        "popularity": <int>,
        "artistRoles": [
          {
            "categoryId": <int>,
            "category": <str>
          }
        ],
        "mixes": {
          "ARTIST_MIX": <str>
        }
      }
    ]
  },
  "albums": {
    "limit": <int>,
    "offset": <int>,
    "totalNumberOfItems": <int>,
    "items": [
      {
        "id": <int>,
        "title": <str>,
        "duration": <int>,
        "streamReady": <bool>,
        "adSupportedStreamReady": <bool>,
        "djReady": <bool>,
        "stemReady": <bool>,
        "streamStartDate": <str>,
        "allowStreaming": <bool>,
        "premiumStreamingOnly": <bool>,
        "numberOfTracks": <int>,
        "numberOfVideos": <int>,
        "numberOfVolumes": <int>,
        "releaseDate": <str>,
        "copyright": <str>,
        "type": "ALBUM",
        "version": <str>,
        "url": <str>,
        "cover": <str>,
        "vibrantColor": <str>,
        "videoCover": <str>,
        "explicit": <bool>,
        "upc": <str>,
        "popularity": <int>,
        "audioQuality": <str>,
        "audioModes": [<str>],
        "mediaMetadata": {
          "tags": [<str>]
        },
        "artist": {
          "id": <int>,
          "name": <str>,
          "type": <str>,
          "picture": <str>
        },
        "artists": [
          {
            "id": <int>,
            "name": <str>,
            "type": <str>,
            "picture": <str>
          }
        ]
      }
    ]
  },
  "playlists": {
    "limit": <int>,
    "offset": <int>,
    "totalNumberOfItems": <int>,
    "items": [
      {
        "uuid": <str>,
        "title": <str>,
        "numberOfTracks": <int>,
        "numberOfVideos": <int>,
        "creator": {
          "id": <int>
        },
        "description": <str>,
        "duration": <int>,
        "lastUpdated": <str>,
        "created": <str>,
        "type": <str>,
        "publicPlaylist": <bool>,
        "url": <str>,
        "image": <str>,
        "popularity": <int>,
        "squareImage": <str>,
        "promotedArtists": [
          {
            "id": <int>,
            "name": <str>,
            "type": <str>,
            "picture": <str>,
          }
        ],
        "lastItemAddedAt": <str>
      }
    ]
  },
  "tracks": {
    "limit": <int>,
    "offset": <int>,
    "totalNumberOfItems": <int>,
    "items": [
      {
        "id": <int>,
        "title": <str>,
        "duration": <int>,
        "replayGain": <float>,
        "peak": <float>,
        "allowStreaming": <bool>,
        "streamReady": <bool>,
        "adSupportedStreamReady": <bool>,
        "djReady": <bool>,
        "stemReady": <bool>,
        "streamStartDate": <str>,
        "premiumStreamingOnly": <bool>,
        "trackNumber": <int>,
        "volumeNumber": <int>,
        "version": <str>,
        "popularity": <int>,
        "copyright": <str>,
        "url": <str>,
        "isrc": <str>,
        "editable": <bool>,
        "explicit": <bool>,
        "audioQuality": <str>,
        "audioModes": [<str>],
        "mediaMetadata": {
          "tags": [<str>]
        },
        "artist": {
          "id": <int>,
          "name": <str>,
          "type": <str>,
          "picture": <str>
        },
        "artists": [
          {
            "id": <int>,
            "name": <str>,
            "type": <str>,
            "picture": <str>
          }
        ],
        "album": {
          "id": <int>,
          "title": <str>,
          "cover": <str>,
          "vibrantColor": <str>,
          "videoCover": <str>
        },
        "mixes": {
          "TRACK_MIX": <str>
        }
      }
    ]
  },
  "videos": {
    "limit": <int>,
    "offset": <int>,
    "totalNumberOfItems": <int>,
    "items": [
      {
        "id": <int>,
        "title": <str>,
        "volumeNumber": <int>,
        "trackNumber": <int>,
        "releaseDate": <str>,
        "imagePath": <str>,
        "imageId": <str>,
        "vibrantColor": <str>,
        "duration": <int>,
        "quality": <str>,
        "streamReady": <bool>,
        "adSupportedStreamReady": <bool>,
        "djReady": <bool>,
        "stemReady": <bool>,
        "streamStartDate": <str>,
        "allowStreaming": <bool>,
        "explicit": <bool>,
        "popularity": <int>,
        "type": <str>,
        "adsUrl": <str>,
        "adsPrePaywallOnly": <bool>,
        "artist": {
          "id": <int>,
          "name": <str>,
          "type": <str>,
          "picture": <str>,
        },
        "artists": [
          {
            "id": <int>,
            "name": <str>,
            "type": <str>,
            "picture": <str>,
          }
        ],
        "album": <dict>
      }
    ]
  },
  "topHit": {
    "value": <dict>,
    "type": <str>
  }
}

get_collection_streams(collection_id: int | str, type: str, *, audio_quality: str = 'HI_RES', video_quality: str = 'HIGH', max_resolution: int = 2160, playback_mode: str = 'STREAM', asset_presentation: str = 'FULL', streaming_session_id: str = None) → list[tuple[bytes, str]][source]#

Get audio and video stream data for items (tracks and videos) in an album, mix, or playlist.

User authentication, authorization scope, and subscription

Requires the r_usr authorization scope if the device code flow was used.

Full track and video playback information and lossless audio is only available with user authentication and an active TIDAL subscription.

High-resolution and immersive audio is only available with the HiFi Plus plan and when the current client credentials are from a supported device.