Client
Server
Reference / @open-music-sdk/client-user / tUserFunctions
Interface: tUserFunctions
Defined in: clients/client-user/src/namespace.ts:17
Every function of this package by its name, each saying what it is for, as it does where it is declared.
It is said twice because of how the package is published: its declarations are rolled into one file, where the modules the functions are declared in become lists of names, with nothing of what was written above each function. An interface keeps what is written above its members. So this is what user(client) is typed from, and what lets an editor say of music.user.getLibrarySong what it says of getLibrarySong. A test holds the two to the same names, the same types and the same words.
Properties
addLibraryPlaylistTracks
ts
readonly addLibraryPlaylistTracks: tEndpoint<[id: string, tracks: readonly tLibraryPlaylistTracksRequestData[], options?: tAddOptions], void, Promise<undefined>, "written">;Defined in: clients/client-user/src/namespace.ts:886
Adds tracks to the end of a playlist in the listener's library: [{ id, type: "songs" }]. It resolves to nothing.
Param
id
The library playlist's id.
Param
tracks
What to add, 1 to 300 of them, each by id and type; nothing else of a track is sent.
Param
options
What else to send with the request, such as a signal to abort it with.
Returns
Nothing: it resolves once Apple has accepted the write.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
addToFavorites
ts
readonly addToFavorites: tEndpoint<[ids: Readonly<Partial<Record<"songs" | "music-videos" | "albums" | "playlists", readonly string[] | undefined>> & Record<string, readonly string[] | undefined>>, options?: tAddOptions], void, Promise<undefined>, "written">;Defined in: clients/client-user/src/namespace.ts:873
Adds resources to the listener's favorites, by their ids: { songs: [...], albums: [...] }. It resolves to nothing: Apple accepts the request and adds them afterwards. Against the live API on 18 October 2026, a song made a favorite had a rating of 1 at once, as a like does, and was put in the library too.
Param
ids
The ids of the resources to add, by type: 1 to 32 types with 1 to 300 ids between them; a type whose list is undefined is left out.
Param
options
What else to send with the request, such as a signal to abort it with.
Returns
Nothing: it resolves once Apple has accepted the write.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
addToLibrary
ts
readonly addToLibrary: tEndpoint<[ids: Readonly<Partial<Record<"songs" | "music-videos" | "albums" | "playlists", readonly string[] | undefined>> & Record<string, readonly string[] | undefined>>, options?: tAddOptions], void, Promise<undefined>, "written">;Defined in: clients/client-user/src/namespace.ts:861
Adds catalog resources to the listener's library, by their ids: { songs: [...], albums: [...] }. It resolves to nothing: Apple accepts the request and adds them afterwards. Against the live API on 18 October 2026, a song, an album, a playlist and a music video each showed in the library within 4 seconds, and within 20 in a second run; the playlist's songs did not go into the library with it either time.
Param
ids
The ids of the catalog resources to add, by type: 1 to 32 types with 1 to 300 ids between them; a type whose list is undefined is left out.
Param
options
What else to send with the request, such as a signal to abort it with.
Returns
Nothing: it resolves once Apple has accepted the write.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
createLibraryPlaylist
ts
readonly createLibraryPlaylist: tEndpoint<[playlist: tLibraryPlaylistCreationRequest, options?: tCreateLibraryPlaylistOptions], tLibraryPlaylistsResponse, Promise<
| tLibraryPlaylist
| undefined>, "written">;Defined in: clients/client-user/src/namespace.ts:273
Makes a playlist in the listener's library: { attributes: { name } }, with its tracks and the folder to put it in under relationships. Resolves to the answer that holds the new playlist. Bound, it gives the playlist, or undefined if Apple's answer holds none: the playlist was made either way. The playlist has to be a plain object, and still one once made into JSON. It is copied as the call is made and sent as it is: what it holds is Apple's to judge, and nothing here limits its size, so limit it yourself if it comes from outside your app.
Param
playlist
The playlist to make: its name under attributes, and its tracks and the folder to put it in under relationships.
Param
options
The language to answer in, and what else to send with the request.
Returns
What Apple sent back of what was written, out of data, or undefined where it sent nothing.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
createLibraryPlaylistFolder
ts
readonly createLibraryPlaylistFolder: tEndpoint<[folder: tLibraryPlaylistFolderCreationRequest, options?: tCreateLibraryPlaylistFolderOptions], tLibraryPlaylistFoldersResponse, Promise<
| tLibraryPlaylistFolder
| undefined>, "written">;Defined in: clients/client-user/src/namespace.ts:330
Makes a playlist folder in the listener's library: { attributes: { name } }, with the folder to put it in under relationships. Resolves to the answer that holds the new folder. Bound, it gives the folder, or undefined if Apple's answer holds none: the folder was made either way. The folder has to be a plain object, and still one once made into JSON. It is copied as the call is made and sent as it is: what it holds is Apple's to judge, and nothing here limits its size, so limit it yourself if it comes from outside your app. Against the live API on 18 October 2026, a folder made with no parent was in the root: it could be read by its id at once, and was among the children of p.playlistsroot, its parent, a second later.
Param
folder
The folder to make: its name under attributes, and the folder to put it in under relationships.
Param
options
The language to answer in, and what else to send with the request.
Returns
What Apple sent back of what was written, out of data, or undefined where it sent nothing.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
deleteAlbumRating
ts
readonly deleteAlbumRating: tEndpoint<[id: string, options?: tDeleteRatingOptions], void, Promise<undefined>, "written">;Defined in: clients/client-user/src/namespace.ts:478
Takes away the listener's rating of the album with an id.
Param
id
The album's id.
Param
options
The language to answer in, and what else to send with the request.
Returns
Nothing: it resolves once Apple has accepted the write.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
deleteLibraryAlbumRating
ts
readonly deleteLibraryAlbumRating: tEndpoint<[id: string, options?: tDeleteRatingOptions], void, Promise<undefined>, "written">;Defined in: clients/client-user/src/namespace.ts:723
Takes away the listener's rating of the library album with an id.
Param
id
The library album's id.
Param
options
The language to answer in, and what else to send with the request.
Returns
Nothing: it resolves once Apple has accepted the write.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
deleteLibraryMusicVideoRating
ts
readonly deleteLibraryMusicVideoRating: tEndpoint<[id: string, options?: tDeleteRatingOptions], void, Promise<undefined>, "written">;Defined in: clients/client-user/src/namespace.ts:772
Takes away the listener's rating of the library music video with an id.
Param
id
The library music video's id.
Param
options
The language to answer in, and what else to send with the request.
Returns
Nothing: it resolves once Apple has accepted the write.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
deleteLibraryPlaylistRating
ts
readonly deleteLibraryPlaylistRating: tEndpoint<[id: string, options?: tDeleteRatingOptions], void, Promise<undefined>, "written">;Defined in: clients/client-user/src/namespace.ts:821
Takes away the listener's rating of the library playlist with an id.
Param
id
The library playlist's id.
Param
options
The language to answer in, and what else to send with the request.
Returns
Nothing: it resolves once Apple has accepted the write.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
deleteLibrarySongRating
ts
readonly deleteLibrarySongRating: tEndpoint<[id: string, options?: tDeleteRatingOptions], void, Promise<undefined>, "written">;Defined in: clients/client-user/src/namespace.ts:674
Takes away the listener's rating of the library song with an id.
Param
id
The library song's id.
Param
options
The language to answer in, and what else to send with the request.
Returns
Nothing: it resolves once Apple has accepted the write.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
deleteMusicVideoRating
ts
readonly deleteMusicVideoRating: tEndpoint<[id: string, options?: tDeleteRatingOptions], void, Promise<undefined>, "written">;Defined in: clients/client-user/src/namespace.ts:527
Takes away the listener's rating of the music video with an id.
Param
id
The music video's id.
Param
options
The language to answer in, and what else to send with the request.
Returns
Nothing: it resolves once Apple has accepted the write.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
deletePlaylistRating
ts
readonly deletePlaylistRating: tEndpoint<[id: string, options?: tDeleteRatingOptions], void, Promise<undefined>, "written">;Defined in: clients/client-user/src/namespace.ts:576
Takes away the listener's rating of the playlist with an id.
Param
id
The playlist's id.
Param
options
The language to answer in, and what else to send with the request.
Returns
Nothing: it resolves once Apple has accepted the write.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
deleteSongRating
ts
readonly deleteSongRating: tEndpoint<[id: string, options?: tDeleteRatingOptions], void, Promise<undefined>, "written">;Defined in: clients/client-user/src/namespace.ts:429
Takes away the listener's rating of the song with an id.
Param
id
The song's id.
Param
options
The language to answer in, and what else to send with the request.
Returns
Nothing: it resolves once Apple has accepted the write.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
deleteStationRating
ts
readonly deleteStationRating: tEndpoint<[id: string, options?: tDeleteRatingOptions], void, Promise<undefined>, "written">;Defined in: clients/client-user/src/namespace.ts:625
Takes away the listener's rating of the station with an id.
Param
id
The station's id.
Param
options
The language to answer in, and what else to send with the request.
Returns
Nothing: it resolves once Apple has accepted the write.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getAlbumRating
ts
readonly getAlbumRating: tEndpoint<[id: string, options?: tEndpointOptions<tRatingsResponse, object, object>], tRatingsResponse, Promise<tRating>, "resource">;Defined in: clients/client-user/src/namespace.ts:441
The listener's rating of the album with an id.
Param
id
The album's id.
Param
options
The language to answer in, and what else to send with the request.
Returns
The rating, out of data.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer holds no rating, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getAlbumRatings
ts
readonly getAlbumRatings: tEndpoint<[ids: readonly string[], options?: tEndpointOptions<tRatingsResponse, object, object>], tRatingsResponse, Promise<tRating[]>, "resources">;Defined in: clients/client-user/src/namespace.ts:453
The listener's ratings of the albums with the ids given.
Param
ids
The albums' ids, 1 to 300 of them.
Param
options
The language to answer in, and what else to send with the request.
Returns
The ratings, out of data: an empty list where Apple sends none.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer is no object or its data is there and is no list, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getLibraryAlbum
ts
readonly getLibraryAlbum: tEndpoint<[id: string, options?: tEndpointOptions<tLibraryAlbumsResponse, object, object>], tLibraryAlbumsResponse, Promise<tLibraryAlbum>, "resource">;Defined in: clients/client-user/src/namespace.ts:77
The album with an id in the listener's library.
Param
id
The library album's id.
Param
options
What to send beside the album.
Returns
The album, out of data.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer holds no album, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getLibraryAlbumRating
ts
readonly getLibraryAlbumRating: tEndpoint<[id: string, options?: tEndpointOptions<tRatingsResponse, object, object>], tRatingsResponse, Promise<tRating>, "resource">;Defined in: clients/client-user/src/namespace.ts:686
The listener's rating of the library album with an id.
Param
id
The library album's id.
Param
options
The language to answer in, and what else to send with the request.
Returns
The rating, out of data.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer holds no rating, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getLibraryAlbumRatings
ts
readonly getLibraryAlbumRatings: tEndpoint<[ids: readonly string[], options?: tEndpointOptions<tRatingsResponse, object, object>], tRatingsResponse, Promise<tRating[]>, "resources">;Defined in: clients/client-user/src/namespace.ts:698
The listener's ratings of the library albums with the ids given.
Param
ids
The library albums' ids, 1 to 300 of them.
Param
options
The language to answer in, and what else to send with the request.
Returns
The ratings, out of data: an empty list where Apple sends none.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer is no object or its data is there and is no list, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getLibraryAlbumRelationship
ts
readonly getLibraryAlbumRelationship: tRelationshipEndpoint<tLibraryAlbumRelationships, object>;Defined in: clients/client-user/src/namespace.ts:113
One relationship of a library album, such as its tracks, a page at a time.
Param
id
The library album's id.
Param
name
The relationship's name, one of the library album's as the type has them; Apple says whether there is such a one.
Param
options
How many to send in one page, where to start, what to send beside them, and the signal and schema of the request.
Returns
Every item of every page, asking for each page as the one before runs out; maxPages says how many pages at most.
Throws
TypeError if an argument is not what it should be, thrown from the call itself, before a loop starts.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if a page is no object or its data is there and is no list, which is an ApiError, each thrown as the loop asks for the page; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getLibraryAlbums
ts
readonly getLibraryAlbums: tEndpoint<[ids: readonly string[], options?: tEndpointOptions<tLibraryAlbumsResponse, object, object>], tLibraryAlbumsResponse, Promise<tLibraryAlbum[]>, "resources">;Defined in: clients/client-user/src/namespace.ts:89
The albums with the ids given in the listener's library.
Param
ids
The library albums' ids, 1 to 300 of them.
Param
options
What to send beside the albums.
Returns
The albums, out of data: an empty list where Apple sends none.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer is no object or its data is there and is no list, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getLibraryArtist
ts
readonly getLibraryArtist: tEndpoint<[id: string, options?: tEndpointOptions<tLibraryArtistsResponse, object, object>], tLibraryArtistsResponse, Promise<tLibraryArtist>, "resource">;Defined in: clients/client-user/src/namespace.ts:125
The artist with an id in the listener's library.
Param
id
The library artist's id.
Param
options
What to send beside the artist.
Returns
The artist, out of data.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer holds no artist, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getLibraryArtistRelationship
ts
readonly getLibraryArtistRelationship: tRelationshipEndpoint<tLibraryArtistRelationships, object>;Defined in: clients/client-user/src/namespace.ts:161
One relationship of a library artist, such as their albums, a page at a time.
Param
id
The library artist's id.
Param
name
The relationship's name, one of the library artist's as the type has them; Apple says whether there is such a one.
Param
options
How many to send in one page, where to start, what to send beside them, and the signal and schema of the request.
Returns
Every item of every page, asking for each page as the one before runs out; maxPages says how many pages at most.
Throws
TypeError if an argument is not what it should be, thrown from the call itself, before a loop starts.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if a page is no object or its data is there and is no list, which is an ApiError, each thrown as the loop asks for the page; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getLibraryArtists
ts
readonly getLibraryArtists: tEndpoint<[ids: readonly string[], options?: tEndpointOptions<tLibraryArtistsResponse, object, object>], tLibraryArtistsResponse, Promise<tLibraryArtist[]>, "resources">;Defined in: clients/client-user/src/namespace.ts:137
The artists with the ids given in the listener's library.
Param
ids
The library artists' ids, 1 to 300 of them.
Param
options
What to send beside the artists.
Returns
The artists, out of data: an empty list where Apple sends none.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer is no object or its data is there and is no list, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getLibraryMusicVideo
ts
readonly getLibraryMusicVideo: tEndpoint<[id: string, options?: tEndpointOptions<tLibraryMusicVideosResponse, object, object>], tLibraryMusicVideosResponse, Promise<tLibraryMusicVideo>, "resource">;Defined in: clients/client-user/src/namespace.ts:173
The music video with an id in the listener's library.
Param
id
The library music video's id.
Param
options
What to send beside the music video.
Returns
The music video, out of data.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer holds no music video, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getLibraryMusicVideoRating
ts
readonly getLibraryMusicVideoRating: tEndpoint<[id: string, options?: tEndpointOptions<tRatingsResponse, object, object>], tRatingsResponse, Promise<tRating>, "resource">;Defined in: clients/client-user/src/namespace.ts:735
The listener's rating of the library music video with an id.
Param
id
The library music video's id.
Param
options
The language to answer in, and what else to send with the request.
Returns
The rating, out of data.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer holds no rating, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getLibraryMusicVideoRatings
ts
readonly getLibraryMusicVideoRatings: tEndpoint<[ids: readonly string[], options?: tEndpointOptions<tRatingsResponse, object, object>], tRatingsResponse, Promise<tRating[]>, "resources">;Defined in: clients/client-user/src/namespace.ts:747
The listener's ratings of the library music videos with the ids given.
Param
ids
The library music videos' ids, 1 to 300 of them.
Param
options
The language to answer in, and what else to send with the request.
Returns
The ratings, out of data: an empty list where Apple sends none.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer is no object or its data is there and is no list, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getLibraryMusicVideoRelationship
ts
readonly getLibraryMusicVideoRelationship: tRelationshipEndpoint<tLibraryMusicVideoRelationships, object>;Defined in: clients/client-user/src/namespace.ts:209
One relationship of a library music video, such as its artists, a page at a time.
Param
id
The library music video's id.
Param
name
The relationship's name, one of the library music video's as the type has them; Apple says whether there is such a one.
Param
options
How many to send in one page, where to start, what to send beside them, and the signal and schema of the request.
Returns
Every item of every page, asking for each page as the one before runs out; maxPages says how many pages at most.
Throws
TypeError if an argument is not what it should be, thrown from the call itself, before a loop starts.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if a page is no object or its data is there and is no list, which is an ApiError, each thrown as the loop asks for the page; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getLibraryMusicVideos
ts
readonly getLibraryMusicVideos: tEndpoint<[ids: readonly string[], options?: tEndpointOptions<tLibraryMusicVideosResponse, object, object>], tLibraryMusicVideosResponse, Promise<tLibraryMusicVideo[]>, "resources">;Defined in: clients/client-user/src/namespace.ts:185
The music videos with the ids given in the listener's library.
Param
ids
The library music videos' ids, 1 to 300 of them.
Param
options
What to send beside the music videos.
Returns
The music videos, out of data: an empty list where Apple sends none.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer is no object or its data is there and is no list, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getLibraryPlaylist
ts
readonly getLibraryPlaylist: tEndpoint<[id: string, options?: tEndpointOptions<tLibraryPlaylistsResponse, object, object>], tLibraryPlaylistsResponse, Promise<tLibraryPlaylist>, "resource">;Defined in: clients/client-user/src/namespace.ts:221
The playlist with an id in the listener's library.
Param
id
The library playlist's id.
Param
options
What to send beside the playlist.
Returns
The playlist, out of data.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer holds no playlist, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getLibraryPlaylistFolder
ts
readonly getLibraryPlaylistFolder: tEndpoint<[id: string, options?: tEndpointOptions<tLibraryPlaylistFoldersResponse, object, object>], tLibraryPlaylistFoldersResponse, Promise<tLibraryPlaylistFolder>, "resource">;Defined in: clients/client-user/src/namespace.ts:287
The playlist folder with an id in the listener's library. The root, p.playlistsroot, was answered 404 by its id against the live API on 18 October 2026, unless asked for with an include, such as ["children"]; a folder made in it was answered without one.
Param
id
The library playlist folder's id.
Param
options
What to send beside the playlist folder.
Returns
The playlist folder, out of data.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer holds no playlist folder, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getLibraryPlaylistFolderRelationship
ts
readonly getLibraryPlaylistFolderRelationship: tRelationshipEndpoint<tLibraryPlaylistFolderRelationships, object>;Defined in: clients/client-user/src/namespace.ts:312
One relationship of a library playlist folder, such as its children, a page at a time.
Param
id
The library playlist folder's id.
Param
name
The relationship's name, one of the library playlist folder's as the type has them; Apple says whether there is such a one.
Param
options
How many to send in one page, where to start, what to send beside them, and the signal and schema of the request.
Returns
Every item of every page, asking for each page as the one before runs out; maxPages says how many pages at most.
Throws
TypeError if an argument is not what it should be, thrown from the call itself, before a loop starts.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if a page is no object or its data is there and is no list, which is an ApiError, each thrown as the loop asks for the page; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getLibraryPlaylistFolders
ts
readonly getLibraryPlaylistFolders: tEndpoint<[ids: readonly string[], options?: tEndpointOptions<tLibraryPlaylistFoldersResponse, object, object>], tLibraryPlaylistFoldersResponse, Promise<tLibraryPlaylistFolder[]>, "resources">;Defined in: clients/client-user/src/namespace.ts:299
The playlist folders with the ids given in the listener's library.
Param
ids
The library playlist folders' ids, 1 to 300 of them.
Param
options
What to send beside the playlist folders.
Returns
The playlist folders, out of data: an empty list where Apple sends none.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer is no object or its data is there and is no list, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getLibraryPlaylistRating
ts
readonly getLibraryPlaylistRating: tEndpoint<[id: string, options?: tEndpointOptions<tRatingsResponse, object, object>], tRatingsResponse, Promise<tRating>, "resource">;Defined in: clients/client-user/src/namespace.ts:784
The listener's rating of the library playlist with an id.
Param
id
The library playlist's id.
Param
options
The language to answer in, and what else to send with the request.
Returns
The rating, out of data.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer holds no rating, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getLibraryPlaylistRatings
ts
readonly getLibraryPlaylistRatings: tEndpoint<[ids: readonly string[], options?: tEndpointOptions<tRatingsResponse, object, object>], tRatingsResponse, Promise<tRating[]>, "resources">;Defined in: clients/client-user/src/namespace.ts:796
The listener's ratings of the library playlists with the ids given.
Param
ids
The library playlists' ids, 1 to 300 of them.
Param
options
The language to answer in, and what else to send with the request.
Returns
The ratings, out of data: an empty list where Apple sends none.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer is no object or its data is there and is no list, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getLibraryPlaylistRelationship
ts
readonly getLibraryPlaylistRelationship: tRelationshipEndpoint<tLibraryPlaylistRelationships, object>;Defined in: clients/client-user/src/namespace.ts:257
One relationship of a library playlist, such as its tracks, a page at a time.
Param
id
The library playlist's id.
Param
name
The relationship's name, one of the library playlist's as the type has them; Apple says whether there is such a one.
Param
options
How many to send in one page, where to start, what to send beside them, and the signal and schema of the request.
Returns
Every item of every page, asking for each page as the one before runs out; maxPages says how many pages at most.
Throws
TypeError if an argument is not what it should be, thrown from the call itself, before a loop starts.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if a page is no object or its data is there and is no list, which is an ApiError, each thrown as the loop asks for the page; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getLibraryPlaylists
ts
readonly getLibraryPlaylists: tEndpoint<[ids: readonly string[], options?: tEndpointOptions<tLibraryPlaylistsResponse, object, object>], tLibraryPlaylistsResponse, Promise<tLibraryPlaylist[]>, "resources">;Defined in: clients/client-user/src/namespace.ts:233
The playlists with the ids given in the listener's library.
Param
ids
The library playlists' ids, 1 to 300 of them.
Param
options
What to send beside the playlists.
Returns
The playlists, out of data: an empty list where Apple sends none.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer is no object or its data is there and is no list, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getLibraryResources
ts
readonly getLibraryResources: tEndpoint<[ids: Readonly<Partial<Record<tLibraryType, readonly string[] | undefined>>>, options?: tLibraryResourcesOptions], tResourceCollectionResponse, Promise<tResource[]>, "resources">;Defined in: clients/client-user/src/namespace.ts:849
Library resources of several types in one request, by their ids: { "library-songs": [...] }. One type at least has to be given.
Param
ids
Ids by type of library resource: 1 to 32 types with 1 to 300 ids between them; a type whose list is undefined is left out.
Param
options
What to send beside the resources.
Returns
The resources, out of data: an empty list where Apple sends none.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer is no object or its data is there and is no list, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getLibrarySong
ts
readonly getLibrarySong: tEndpoint<[id: string, options?: tEndpointOptions<tLibrarySongsResponse, object, object>], tLibrarySongsResponse, Promise<tLibrarySong>, "resource">;Defined in: clients/client-user/src/namespace.ts:29
The song with an id in the listener's library.
Param
id
The library song's id.
Param
options
What to send beside the song.
Returns
The song, out of data.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer holds no song, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getLibrarySongRating
ts
readonly getLibrarySongRating: tEndpoint<[id: string, options?: tEndpointOptions<tRatingsResponse, object, object>], tRatingsResponse, Promise<tRating>, "resource">;Defined in: clients/client-user/src/namespace.ts:637
The listener's rating of the library song with an id.
Param
id
The library song's id.
Param
options
The language to answer in, and what else to send with the request.
Returns
The rating, out of data.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer holds no rating, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getLibrarySongRatings
ts
readonly getLibrarySongRatings: tEndpoint<[ids: readonly string[], options?: tEndpointOptions<tRatingsResponse, object, object>], tRatingsResponse, Promise<tRating[]>, "resources">;Defined in: clients/client-user/src/namespace.ts:649
The listener's ratings of the library songs with the ids given.
Param
ids
The library songs' ids, 1 to 300 of them.
Param
options
The language to answer in, and what else to send with the request.
Returns
The ratings, out of data: an empty list where Apple sends none.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer is no object or its data is there and is no list, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getLibrarySongRelationship
ts
readonly getLibrarySongRelationship: tRelationshipEndpoint<tLibrarySongRelationships, object>;Defined in: clients/client-user/src/namespace.ts:65
One relationship of a library song, such as its albums, a page at a time.
Param
id
The library song's id.
Param
name
The relationship's name, one of the library song's as the type has them; Apple says whether there is such a one.
Param
options
How many to send in one page, where to start, what to send beside them, and the signal and schema of the request.
Returns
Every item of every page, asking for each page as the one before runs out; maxPages says how many pages at most.
Throws
TypeError if an argument is not what it should be, thrown from the call itself, before a loop starts.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if a page is no object or its data is there and is no list, which is an ApiError, each thrown as the loop asks for the page; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getLibrarySongs
ts
readonly getLibrarySongs: tEndpoint<[ids: readonly string[], options?: tEndpointOptions<tLibrarySongsResponse, object, object>], tLibrarySongsResponse, Promise<tLibrarySong[]>, "resources">;Defined in: clients/client-user/src/namespace.ts:41
The songs with the ids given in the listener's library.
Param
ids
The library songs' ids, 1 to 300 of them.
Param
options
What to send beside the songs.
Returns
The songs, out of data: an empty list where Apple sends none.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer is no object or its data is there and is no list, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getMusicSummariesByYear
ts
readonly getMusicSummariesByYear: tEndpoint<[values: readonly string[], options?: tEndpointOptions<tMusicSummariesResponse, object, tViewsOption<tMusicSummaryViews>>], tMusicSummariesResponse, Promise<tMusicSummary[]>, "resources">;Defined in: clients/client-user/src/namespace.ts:968
The listener's replay: a summary of what they played in each of the years given. The one year Apple takes at present is "latest".
Param
values
The years, 1 to 300 of them; "latest" is the one Apple takes at present.
Param
options
The views to send with each summary, and what else to send beside it.
Returns
The summaries, out of data: an empty list where Apple sends none.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer is no object or its data is there and is no list, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getMusicVideoRating
ts
readonly getMusicVideoRating: tEndpoint<[id: string, options?: tEndpointOptions<tRatingsResponse, object, object>], tRatingsResponse, Promise<tRating>, "resource">;Defined in: clients/client-user/src/namespace.ts:490
The listener's rating of the music video with an id.
Param
id
The music video's id.
Param
options
The language to answer in, and what else to send with the request.
Returns
The rating, out of data.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer holds no rating, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getMusicVideoRatings
ts
readonly getMusicVideoRatings: tEndpoint<[ids: readonly string[], options?: tEndpointOptions<tRatingsResponse, object, object>], tRatingsResponse, Promise<tRating[]>, "resources">;Defined in: clients/client-user/src/namespace.ts:502
The listener's ratings of the music videos with the ids given.
Param
ids
The music videos' ids, 1 to 300 of them.
Param
options
The language to answer in, and what else to send with the request.
Returns
The ratings, out of data: an empty list where Apple sends none.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer is no object or its data is there and is no list, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getPersonalRecommendation
ts
readonly getPersonalRecommendation: tEndpoint<[id: string, options?: tEndpointOptions<tPersonalRecommendationResponse, object, object>], tPersonalRecommendationResponse, Promise<tPersonalRecommendation>, "resource">;Defined in: clients/client-user/src/namespace.ts:342
The recommendation with an id, of the ones made for the listener.
Param
id
The recommendation's id.
Param
options
What to send beside the recommendation.
Returns
The recommendation, out of data.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer holds no recommendation, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getPersonalRecommendationRelationship
ts
readonly getPersonalRecommendationRelationship: tRelationshipEndpoint<tPersonalRecommendationRelationships, object>;Defined in: clients/client-user/src/namespace.ts:378
One relationship of a recommendation, such as its contents, a page at a time.
Param
id
The recommendation's id.
Param
name
The relationship's name, one of the recommendation's as the type has them; Apple says whether there is such a one.
Param
options
How many to send in one page, where to start, what to send beside them, and the signal and schema of the request.
Returns
Every item of every page, asking for each page as the one before runs out; maxPages says how many pages at most.
Throws
TypeError if an argument is not what it should be, thrown from the call itself, before a loop starts.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if a page is no object or its data is there and is no list, which is an ApiError, each thrown as the loop asks for the page; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getPersonalRecommendations
ts
readonly getPersonalRecommendations: tEndpoint<[ids: readonly string[], options?: tEndpointOptions<tPersonalRecommendationResponse, object, object>], tPersonalRecommendationResponse, Promise<tPersonalRecommendation[]>, "resources">;Defined in: clients/client-user/src/namespace.ts:354
The recommendations with the ids given, of the ones made for the listener.
Param
ids
The recommendations' ids, 1 to 300 of them.
Param
options
What to send beside the recommendations.
Returns
The recommendations, out of data: an empty list where Apple sends none.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer is no object or its data is there and is no list, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getPersonalStation
ts
readonly getPersonalStation: tEndpoint<[options?: tPersonalStationOptions], tStationsResponse, Promise<tStation>, "resource">;Defined in: clients/client-user/src/namespace.ts:980
The listener's own station, which plays what Apple picks for them. It is kept in the catalog, and is the one resource there that is asked for with the Music User Token.
Param
options
The storefront whose catalog the station is in, and what to send beside it.
Returns
The station, out of data.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, if the client has no storefront to ask in, or a schema finds issues, or if the answer holds no station, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getPlaylistRating
ts
readonly getPlaylistRating: tEndpoint<[id: string, options?: tEndpointOptions<tRatingsResponse, object, object>], tRatingsResponse, Promise<tRating>, "resource">;Defined in: clients/client-user/src/namespace.ts:539
The listener's rating of the playlist with an id.
Param
id
The playlist's id.
Param
options
The language to answer in, and what else to send with the request.
Returns
The rating, out of data.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer holds no rating, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getPlaylistRatings
ts
readonly getPlaylistRatings: tEndpoint<[ids: readonly string[], options?: tEndpointOptions<tRatingsResponse, object, object>], tRatingsResponse, Promise<tRating[]>, "resources">;Defined in: clients/client-user/src/namespace.ts:551
The listener's ratings of the playlists with the ids given.
Param
ids
The playlists' ids, 1 to 300 of them.
Param
options
The language to answer in, and what else to send with the request.
Returns
The ratings, out of data: an empty list where Apple sends none.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer is no object or its data is there and is no list, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getRootLibraryPlaylistFolder
ts
readonly getRootLibraryPlaylistFolder: tEndpoint<[options?: tRootLibraryPlaylistFolderOptions], tLibraryPlaylistFoldersResponse, Promise<tLibraryPlaylistFolder>, "resource">;Defined in: clients/client-user/src/namespace.ts:901
The folder every playlist and playlist folder of the listener's library is in, at the top: where to start going down from. It is asked for with its children, unless options.include names what to include instead: against the live API on 18 October 2026, Apple answered the documented request, which names nothing to include, with no folder at all, data and meta.filters.identity.playlistsroot both empty. Asked with an include, it answered with the root, p.playlistsroot, which has no attributes.
Param
options
What to send beside the folder: its children, unless include names what to send instead.
Returns
The root folder, out of data, with its first page of children under relationships.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer holds no folder, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getSongRating
ts
readonly getSongRating: tEndpoint<[id: string, options?: tEndpointOptions<tRatingsResponse, object, object>], tRatingsResponse, Promise<tRating>, "resource">;Defined in: clients/client-user/src/namespace.ts:391
The listener's rating of the song with an id. A song the listener never rated is answered 404, an ApiError, as it was against the live API on 18 October 2026.
Param
id
The song's id.
Param
options
The language to answer in, and what else to send with the request.
Returns
The rating, out of data.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer holds no rating, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getSongRatings
ts
readonly getSongRatings: tEndpoint<[ids: readonly string[], options?: tEndpointOptions<tRatingsResponse, object, object>], tRatingsResponse, Promise<tRating[]>, "resources">;Defined in: clients/client-user/src/namespace.ts:404
The listener's ratings of the songs with the ids given. Songs the listener never rated are left out, as they were against the live API on 18 October 2026.
Param
ids
The songs' ids, 1 to 300 of them.
Param
options
The language to answer in, and what else to send with the request.
Returns
The ratings, out of data: an empty list where Apple sends none.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer is no object or its data is there and is no list, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getStationRating
ts
readonly getStationRating: tEndpoint<[id: string, options?: tEndpointOptions<tRatingsResponse, object, object>], tRatingsResponse, Promise<tRating>, "resource">;Defined in: clients/client-user/src/namespace.ts:588
The listener's rating of the station with an id.
Param
id
The station's id.
Param
options
The language to answer in, and what else to send with the request.
Returns
The rating, out of data.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer holds no rating, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getStationRatings
ts
readonly getStationRatings: tEndpoint<[ids: readonly string[], options?: tEndpointOptions<tRatingsResponse, object, object>], tRatingsResponse, Promise<tRating[]>, "resources">;Defined in: clients/client-user/src/namespace.ts:600
The listener's ratings of the stations with the ids given.
Param
ids
The stations' ids, 1 to 300 of them.
Param
options
The language to answer in, and what else to send with the request.
Returns
The ratings, out of data: an empty list where Apple sends none.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer is no object or its data is there and is no list, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
getUserStorefront
ts
readonly getUserStorefront: tEndpoint<[options?: tUserStorefrontOptions], tStorefrontsResponse, Promise<tStorefront>, "resource">;Defined in: clients/client-user/src/namespace.ts:991
The storefront the listener's account is in: the one whose catalog they see.
Param
options
What to send beside the storefront.
Returns
The storefront, out of data.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if the answer holds no storefront, which is an ApiError; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
listHeavyRotation
ts
readonly listHeavyRotation: tEndpoint<[options?: tReadOptions<tPaged<tPaginatedResourceCollectionResponse>> & object & tWalkOptions], tPaged<tPaginatedResourceCollectionResponse>, AsyncIterable<tResource, any, any>, "pages">;Defined in: clients/client-user/src/namespace.ts:923
What the listener plays most at present, a page at a time.
Param
options
How many to send in one page, where to start, what to send beside them, and the signal and schema of the request.
Returns
Every item of every page, asking for each page as the one before runs out; maxPages says how many pages at most.
Throws
TypeError if an argument is not what it should be, thrown from the call itself, before a loop starts.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if a page is no object or its data is there and is no list, which is an ApiError, each thrown as the loop asks for the page; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
listLibraryAlbums
ts
readonly listLibraryAlbums: tEndpoint<[options?: tReadOptions<tPaged<tLibraryAlbumsResponse>> & object & tWalkOptions], tPaged<tLibraryAlbumsResponse>, AsyncIterable<tLibraryAlbum, any, any>, "pages">;Defined in: clients/client-user/src/namespace.ts:100
Every album in the listener's library, a page at a time.
Param
options
How many to send in one page, where to start, what to send beside them, and the signal and schema of the request.
Returns
Every album of every page, asking for each page as the one before runs out; maxPages says how many pages at most.
Throws
TypeError if an argument is not what it should be, thrown from the call itself, before a loop starts.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if a page is no object or its data is there and is no list, which is an ApiError, each thrown as the loop asks for the page; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
listLibraryArtists
ts
readonly listLibraryArtists: tEndpoint<[options?: tReadOptions<tPaged<tLibraryArtistsResponse>> & object & tWalkOptions], tPaged<tLibraryArtistsResponse>, AsyncIterable<tLibraryArtist, any, any>, "pages">;Defined in: clients/client-user/src/namespace.ts:148
Every artist in the listener's library, a page at a time.
Param
options
How many to send in one page, where to start, what to send beside them, and the signal and schema of the request.
Returns
Every artist of every page, asking for each page as the one before runs out; maxPages says how many pages at most.
Throws
TypeError if an argument is not what it should be, thrown from the call itself, before a loop starts.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if a page is no object or its data is there and is no list, which is an ApiError, each thrown as the loop asks for the page; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
listLibraryMusicVideos
ts
readonly listLibraryMusicVideos: tEndpoint<[options?: tReadOptions<tPaged<tLibraryMusicVideosResponse>> & object & tWalkOptions], tPaged<tLibraryMusicVideosResponse>, AsyncIterable<tLibraryMusicVideo, any, any>, "pages">;Defined in: clients/client-user/src/namespace.ts:196
Every music video in the listener's library, a page at a time.
Param
options
How many to send in one page, where to start, what to send beside them, and the signal and schema of the request.
Returns
Every music video of every page, asking for each page as the one before runs out; maxPages says how many pages at most.
Throws
TypeError if an argument is not what it should be, thrown from the call itself, before a loop starts.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if a page is no object or its data is there and is no list, which is an ApiError, each thrown as the loop asks for the page; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
listLibraryPlaylists
ts
readonly listLibraryPlaylists: tEndpoint<[options?: tReadOptions<tPaged<tLibraryPlaylistsResponse>> & object & tWalkOptions], tPaged<tLibraryPlaylistsResponse>, AsyncIterable<tLibraryPlaylist, any, any>, "pages">;Defined in: clients/client-user/src/namespace.ts:244
Every playlist in the listener's library, a page at a time.
Param
options
How many to send in one page, where to start, what to send beside them, and the signal and schema of the request.
Returns
Every playlist of every page, asking for each page as the one before runs out; maxPages says how many pages at most.
Throws
TypeError if an argument is not what it should be, thrown from the call itself, before a loop starts.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if a page is no object or its data is there and is no list, which is an ApiError, each thrown as the loop asks for the page; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
listLibrarySongs
ts
readonly listLibrarySongs: tEndpoint<[options?: tReadOptions<tPaged<tLibrarySongsResponse>> & object & tWalkOptions], tPaged<tLibrarySongsResponse>, AsyncIterable<tLibrarySong, any, any>, "pages">;Defined in: clients/client-user/src/namespace.ts:52
Every song in the listener's library, a page at a time.
Param
options
How many to send in one page, where to start, what to send beside them, and the signal and schema of the request.
Returns
Every song of every page, asking for each page as the one before runs out; maxPages says how many pages at most.
Throws
TypeError if an argument is not what it should be, thrown from the call itself, before a loop starts.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if a page is no object or its data is there and is no list, which is an ApiError, each thrown as the loop asks for the page; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
listPersonalRecommendations
ts
readonly listPersonalRecommendations: tEndpoint<[options?: tReadOptions<tPaged<tPersonalRecommendationResponse>> & object & tWalkOptions], tPaged<tPersonalRecommendationResponse>, AsyncIterable<tPersonalRecommendation, any, any>, "pages">;Defined in: clients/client-user/src/namespace.ts:365
Every recommendation made for the listener, a page at a time.
Param
options
How many to send in one page, where to start, what to send beside them, and the signal and schema of the request.
Returns
Every recommendation of every page, asking for each page as the one before runs out; maxPages says how many pages at most.
Throws
TypeError if an argument is not what it should be, thrown from the call itself, before a loop starts.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if a page is no object or its data is there and is no list, which is an ApiError, each thrown as the loop asks for the page; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
listRecentlyAdded
ts
readonly listRecentlyAdded: tEndpoint<[options?: tReadOptions<tPaged<tResourceCollectionResponse>> & object & tWalkOptions], tPaged<tResourceCollectionResponse>, AsyncIterable<tResource, any, any>, "pages">;Defined in: clients/client-user/src/namespace.ts:912
What the listener added to their library lately, newest first, a page at a time.
Param
options
How many to send in one page, where to start, what to send beside them, and the signal and schema of the request.
Returns
Every item of every page, asking for each page as the one before runs out; maxPages says how many pages at most.
Throws
TypeError if an argument is not what it should be, thrown from the call itself, before a loop starts.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if a page is no object or its data is there and is no list, which is an ApiError, each thrown as the loop asks for the page; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
listRecentlyPlayed
ts
readonly listRecentlyPlayed: tEndpoint<[options?: tReadOptions<tPaged<tPaginatedResourceCollectionResponse>> & object & tRecentlyPlayedTypesOption & tWalkOptions], tPaged<tPaginatedResourceCollectionResponse>, AsyncIterable<tResource, any, any>, "pages">;Defined in: clients/client-user/src/namespace.ts:934
What the listener played lately, newest first, a page at a time: the albums, playlists and stations, not the tracks in them.
Param
options
The types to keep to, how many to send in one page, where to start, what to send beside them, and the signal and schema of the request.
Returns
Every item of every page, asking for each page as the one before runs out; maxPages says how many pages at most.
Throws
TypeError if an argument is not what it should be, thrown from the call itself, before a loop starts.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if a page is no object or its data is there and is no list, which is an ApiError, each thrown as the loop asks for the page; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
listRecentlyPlayedStations
ts
readonly listRecentlyPlayedStations: tEndpoint<[options?: tReadOptions<tPaged<tPaginatedResourceCollectionResponse>> & object & tWalkOptions], tPaged<tPaginatedResourceCollectionResponse>, AsyncIterable<tResource, any, any>, "pages">;Defined in: clients/client-user/src/namespace.ts:956
The radio stations the listener played lately, newest first, a page at a time.
Param
options
How many to send in one page, where to start, what to send beside them, and the signal and schema of the request.
Returns
Every station of every page, asking for each page as the one before runs out; maxPages says how many pages at most.
Throws
TypeError if an argument is not what it should be, thrown from the call itself, before a loop starts.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if a page is no object or its data is there and is no list, which is an ApiError, each thrown as the loop asks for the page; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
listRecentlyPlayedTracks
ts
readonly listRecentlyPlayedTracks: tEndpoint<[options?: tReadOptions<tPaged<tPaginatedResourceCollectionResponse>> & object & tRecentlyPlayedTrackTypesOption & tWalkOptions], tPaged<tPaginatedResourceCollectionResponse>, AsyncIterable<tResource, any, any>, "pages">;Defined in: clients/client-user/src/namespace.ts:945
The tracks the listener played lately, newest first, a page at a time.
Param
options
The types to keep to, how many to send in one page, where to start, what to send beside them, and the signal and schema of the request.
Returns
Every track of every page, asking for each page as the one before runs out; maxPages says how many pages at most.
Throws
TypeError if an argument is not what it should be, thrown from the call itself, before a loop starts.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues, or if a page is no object or its data is there and is no list, which is an ApiError, each thrown as the loop asks for the page; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
searchLibrary
ts
readonly searchLibrary: tEndpoint<[term: string, options: tSearchLibraryOptions], tLibrarySearchResponse, Promise<tLibrarySearchResponse>, "answer">;Defined in: clients/client-user/src/namespace.ts:837
Searches the listener's library for a term, and resolves to the results by type, each one a first page. limit and offset apply to every type asked for. A next link of a search answers with results by type again, not with a page, so paginate stops after the first page: to get more of one type, ask again with a larger offset. Against the live API on 18 October 2026, the whole name of a song of three words or more found nothing, while the first word of it found the song.
Param
term
What to search for, 1 to 256 characters.
Param
options
The types to look for, which have to be given; how many of each to send and where to start; and what to send beside each.
Returns
What Apple answered: the results by type under results, each a first page of its own.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
setAlbumRating
ts
readonly setAlbumRating: tEndpoint<[id: string, value: -1 | 1, options?: tSetRatingOptions], tRatingsResponse, Promise<tRating | undefined>, "written">;Defined in: clients/client-user/src/namespace.ts:466
Sets the listener's rating of the album with an id: 1 for a like, -1 for a dislike.
Param
id
The album's id.
Param
value
The rating: 1 for a like, -1 for a dislike.
Param
options
The language to answer in, and what else to send with the request.
Returns
What Apple sent back of what was written, out of data, or undefined where it sent nothing.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
setLibraryAlbumRating
ts
readonly setLibraryAlbumRating: tEndpoint<[id: string, value: -1 | 1, options?: tSetRatingOptions], tRatingsResponse, Promise<tRating | undefined>, "written">;Defined in: clients/client-user/src/namespace.ts:711
Sets the listener's rating of the library album with an id: 1 for a like, -1 for a dislike.
Param
id
The library album's id.
Param
value
The rating: 1 for a like, -1 for a dislike.
Param
options
The language to answer in, and what else to send with the request.
Returns
What Apple sent back of what was written, out of data, or undefined where it sent nothing.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
setLibraryMusicVideoRating
ts
readonly setLibraryMusicVideoRating: tEndpoint<[id: string, value: -1 | 1, options?: tSetRatingOptions], tRatingsResponse, Promise<tRating | undefined>, "written">;Defined in: clients/client-user/src/namespace.ts:760
Sets the listener's rating of the library music video with an id: 1 for a like, -1 for a dislike.
Param
id
The library music video's id.
Param
value
The rating: 1 for a like, -1 for a dislike.
Param
options
The language to answer in, and what else to send with the request.
Returns
What Apple sent back of what was written, out of data, or undefined where it sent nothing.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
setLibraryPlaylistRating
ts
readonly setLibraryPlaylistRating: tEndpoint<[id: string, value: -1 | 1, options?: tSetRatingOptions], tRatingsResponse, Promise<tRating | undefined>, "written">;Defined in: clients/client-user/src/namespace.ts:809
Sets the listener's rating of the library playlist with an id: 1 for a like, -1 for a dislike.
Param
id
The library playlist's id.
Param
value
The rating: 1 for a like, -1 for a dislike.
Param
options
The language to answer in, and what else to send with the request.
Returns
What Apple sent back of what was written, out of data, or undefined where it sent nothing.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
setLibrarySongRating
ts
readonly setLibrarySongRating: tEndpoint<[id: string, value: -1 | 1, options?: tSetRatingOptions], tRatingsResponse, Promise<tRating | undefined>, "written">;Defined in: clients/client-user/src/namespace.ts:662
Sets the listener's rating of the library song with an id: 1 for a like, -1 for a dislike.
Param
id
The library song's id.
Param
value
The rating: 1 for a like, -1 for a dislike.
Param
options
The language to answer in, and what else to send with the request.
Returns
What Apple sent back of what was written, out of data, or undefined where it sent nothing.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
setMusicVideoRating
ts
readonly setMusicVideoRating: tEndpoint<[id: string, value: -1 | 1, options?: tSetRatingOptions], tRatingsResponse, Promise<tRating | undefined>, "written">;Defined in: clients/client-user/src/namespace.ts:515
Sets the listener's rating of the music video with an id: 1 for a like, -1 for a dislike.
Param
id
The music video's id.
Param
value
The rating: 1 for a like, -1 for a dislike.
Param
options
The language to answer in, and what else to send with the request.
Returns
What Apple sent back of what was written, out of data, or undefined where it sent nothing.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
setPlaylistRating
ts
readonly setPlaylistRating: tEndpoint<[id: string, value: -1 | 1, options?: tSetRatingOptions], tRatingsResponse, Promise<tRating | undefined>, "written">;Defined in: clients/client-user/src/namespace.ts:564
Sets the listener's rating of the playlist with an id: 1 for a like, -1 for a dislike.
Param
id
The playlist's id.
Param
value
The rating: 1 for a like, -1 for a dislike.
Param
options
The language to answer in, and what else to send with the request.
Returns
What Apple sent back of what was written, out of data, or undefined where it sent nothing.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
setSongRating
ts
readonly setSongRating: tEndpoint<[id: string, value: -1 | 1, options?: tSetRatingOptions], tRatingsResponse, Promise<tRating | undefined>, "written">;Defined in: clients/client-user/src/namespace.ts:417
Sets the listener's rating of the song with an id: 1 for a like, -1 for a dislike.
Param
id
The song's id.
Param
value
The rating: 1 for a like, -1 for a dislike.
Param
options
The language to answer in, and what else to send with the request.
Returns
What Apple sent back of what was written, out of data, or undefined where it sent nothing.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.
setStationRating
ts
readonly setStationRating: tEndpoint<[id: string, value: -1 | 1, options?: tSetRatingOptions], tRatingsResponse, Promise<tRating | undefined>, "written">;Defined in: clients/client-user/src/namespace.ts:613
Sets the listener's rating of the station with an id: 1 for a like, -1 for a dislike.
Param
id
The station's id.
Param
value
The rating: 1 for a like, -1 for a dislike.
Param
options
The language to answer in, and what else to send with the request.
Returns
What Apple sent back of what was written, out of data, or undefined where it sent nothing.
Throws
TypeError if an argument is not what it should be, before Apple is asked.
Throws
AppleMusicError if Apple, the network, or a token provider fails, or a schema finds issues; _tag says which.
Throws
The reason options.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as client.request passes it on.