openapi: 3.0.3
info:
title: Last.fm API
description: >-
The Last.fm API provides access to the Last.fm music platform, enabling developers to
retrieve music metadata for artists, albums, and tracks; read and write user scrobble data;
explore personalized recommendations; access global and geographic music charts; search the
music catalog; and retrieve user listening histories and social data such as friends and
loved tracks. Authentication is required for write operations including scrobbling. The API
uses REST over HTTP with responses available in JSON or XML format.
version: 2.0.0
contact:
name: Last.fm API Support
url: https://www.last.fm/api
termsOfService: https://www.last.fm/api/tos
license:
name: Last.fm API Terms of Service
url: https://www.last.fm/api/tos
externalDocs:
description: Last.fm API Documentation
url: https://www.last.fm/api/intro
servers:
- url: https://ws.audioscrobbler.com/2.0
description: Last.fm API endpoint
security: []
tags:
- name: Album
description: Methods for retrieving album metadata and managing album tags
- name: Artist
description: Methods for retrieving artist metadata and managing artist tags
- name: Auth
description: Authentication methods for obtaining session keys
- name: Chart
description: Global chart data for top artists, tracks, and tags
- name: Geo
description: Geographic music data by country
- name: Library
description: Access to a user's music library
- name: Tag
description: Methods for browsing music by community-applied tags
- name: Track
description: Methods for retrieving track metadata, scrobbling, and managing track tags
- name: User
description: Methods for accessing user profiles, listening history, and social data
paths:
/:
get:
operationId: album_getInfo
summary: Get album info
description: >-
Get the metadata and tracklisting for an album on Last.fm using the album name or
a MusicBrainz id.
tags:
- Album
parameters:
- name: method
in: query
required: true
schema:
type: string
enum:
- album.getInfo
description: API method name
- name: artist
in: query
required: false
schema:
type: string
description: The artist name. Required unless mbid is provided.
- name: album
in: query
required: false
schema:
type: string
description: The album name. Required unless mbid is provided.
- name: mbid
in: query
required: false
schema:
type: string
description: The MusicBrainz ID for the album.
- name: autocorrect
in: query
required: false
schema:
type: integer
enum: [0, 1]
description: Transform misspelled artist names into correct artist names (0 or 1).
- name: username
in: query
required: false
schema:
type: string
description: The username for the context of the request. Includes playcount in response.
- name: lang
in: query
required: false
schema:
type: string
description: The language to return the biography in, expressed as an ISO 639 alpha-2 code.
- name: api_key
in: query
required: true
schema:
type: string
description: A Last.fm API key.
- name: format
in: query
required: false
schema:
type: string
enum: [json, xml]
description: The response format (default is xml).
responses:
'200':
description: Successful album info response
content:
application/json:
schema:
$ref: '#/components/schemas/AlbumInfoResponse'
post:
operationId: album_addTags
summary: Add tags to an album
description: Tag an album using a list of user supplied tags.
tags:
- Album
parameters:
- name: method
in: query
required: true
schema:
type: string
enum:
- album.addTags
- name: artist
in: query
required: true
schema:
type: string
description: The artist name.
- name: album
in: query
required: true
schema:
type: string
description: The album name.
- name: tags
in: query
required: true
schema:
type: string
description: A comma delimited list of user supplied tags to apply to this album. Accepts a maximum of 10 tags.
- name: api_key
in: query
required: true
schema:
type: string
description: A Last.fm API key.
- name: api_sig
in: query
required: true
schema:
type: string
description: A Last.fm method signature. See authentication.
- name: sk
in: query
required: true
schema:
type: string
description: A session key generated by authenticating a user via the authentication API.
responses:
'200':
description: Tags added successfully
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
security:
- SessionKey: []
x-paths:
artist_getInfo:
get:
operationId: artist_getInfo
summary: Get artist info
description: Get the metadata for an artist on Last.fm. Includes biography, truncated at 300 characters.
tags:
- Artist
parameters:
- name: method
in: query
required: true
schema:
type: string
enum:
- artist.getInfo
- name: artist
in: query
required: false
schema:
type: string
description: The artist name. Required unless mbid is provided.
- name: mbid
in: query
required: false
schema:
type: string
description: The MusicBrainz ID for the artist. Takes priority over artist parameter if set.
- name: lang
in: query
required: false
schema:
type: string
description: The language to return the biography in, expressed as an ISO 639 alpha-2 code.
- name: autocorrect
in: query
required: false
schema:
type: integer
enum: [0, 1]
description: Transform misspelled artist names into correct artist names (0 or 1).
- name: username
in: query
required: false
schema:
type: string
description: The username for the context of the request. Includes the user's playcount for this artist.
- name: api_key
in: query
required: true
schema:
type: string
description: A Last.fm API key.
- name: format
in: query
required: false
schema:
type: string
enum: [json, xml]
responses:
'200':
description: Successful artist info response
content:
application/json:
schema:
$ref: '#/components/schemas/ArtistInfoResponse'
artist_getSimilar:
get:
operationId: artist_getSimilar
summary: Get similar artists
description: Get all the artists similar to this artist.
tags:
- Artist
parameters:
- name: method
in: query
required: true
schema:
type: string
enum:
- artist.getSimilar
- name: artist
in: query
required: false
schema:
type: string
- name: mbid
in: query
required: false
schema:
type: string
- name: autocorrect
in: query
required: false
schema:
type: integer
enum: [0, 1]
- name: limit
in: query
required: false
schema:
type: integer
description: Limit the number of similar artists returned.
- name: api_key
in: query
required: true
schema:
type: string
- name: format
in: query
required: false
schema:
type: string
enum: [json, xml]
responses:
'200':
description: List of similar artists
content:
application/json:
schema:
$ref: '#/components/schemas/SimilarArtistsResponse'
artist_search:
get:
operationId: artist_search
summary: Search for an artist
description: Search for an artist by name. Returns artist matches sorted by relevance.
tags:
- Artist
parameters:
- name: method
in: query
required: true
schema:
type: string
enum:
- artist.search
- name: artist
in: query
required: true
schema:
type: string
description: The artist name to search for.
- name: limit
in: query
required: false
schema:
type: integer
default: 30
description: The number of results to fetch per page. Defaults to 30.
- name: page
in: query
required: false
schema:
type: integer
default: 1
description: The page number to fetch. Defaults to first page.
- name: api_key
in: query
required: true
schema:
type: string
- name: format
in: query
required: false
schema:
type: string
enum: [json, xml]
responses:
'200':
description: Artist search results
content:
application/json:
schema:
$ref: '#/components/schemas/ArtistSearchResponse'
track_scrobble:
post:
operationId: track_scrobble
summary: Scrobble tracks
description: >-
Used to add a track-play to a user's profile. Accepts up to 50 batch scrobbles. Requires
authentication via session key.
tags:
- Track
parameters:
- name: method
in: query
required: true
schema:
type: string
enum:
- track.scrobble
- name: artist[i]
in: query
required: true
schema:
type: string
description: The artist name (use index i for batch scrobbles, e.g. artist[0]).
- name: track[i]
in: query
required: true
schema:
type: string
description: The track name (use index i for batch scrobbles).
- name: timestamp[i]
in: query
required: true
schema:
type: integer
description: The time the track started playing, in UNIX timestamp format.
- name: album[i]
in: query
required: false
schema:
type: string
description: The album name.
- name: albumArtist[i]
in: query
required: false
schema:
type: string
description: The album artist, if different from the track artist.
- name: trackNumber[i]
in: query
required: false
schema:
type: integer
description: The track number of the track on the album.
- name: mbid[i]
in: query
required: false
schema:
type: string
description: The MusicBrainz Track ID.
- name: duration[i]
in: query
required: false
schema:
type: integer
description: The length of the track in seconds.
- name: chosenByUser[i]
in: query
required: false
schema:
type: integer
enum: [0, 1]
description: Set to 1 if the user chose this song, or 0 if the song was chosen by someone else (radio, random, etc).
- name: api_key
in: query
required: true
schema:
type: string
- name: api_sig
in: query
required: true
schema:
type: string
- name: sk
in: query
required: true
schema:
type: string
description: A session key generated by authenticating a user.
responses:
'200':
description: Scrobble response with accepted and ignored counts
content:
application/json:
schema:
$ref: '#/components/schemas/ScrobbleResponse'
security:
- SessionKey: []
track_updateNowPlaying:
post:
operationId: track_updateNowPlaying
summary: Update now playing
description: Notify Last.fm that a user has started listening to a track. Requires authentication.
tags:
- Track
parameters:
- name: method
in: query
required: true
schema:
type: string
enum:
- track.updateNowPlaying
- name: artist
in: query
required: true
schema:
type: string
- name: track
in: query
required: true
schema:
type: string
- name: album
in: query
required: false
schema:
type: string
- name: albumArtist
in: query
required: false
schema:
type: string
- name: trackNumber
in: query
required: false
schema:
type: integer
- name: mbid
in: query
required: false
schema:
type: string
- name: duration
in: query
required: false
schema:
type: integer
- name: api_key
in: query
required: true
schema:
type: string
- name: api_sig
in: query
required: true
schema:
type: string
- name: sk
in: query
required: true
schema:
type: string
responses:
'200':
description: Now playing status updated
content:
application/json:
schema:
$ref: '#/components/schemas/NowPlayingResponse'
security:
- SessionKey: []
track_getInfo:
get:
operationId: track_getInfo
summary: Get track info
description: Get the metadata for a track on Last.fm using the artist/track name or a MusicBrainz id.
tags:
- Track
parameters:
- name: method
in: query
required: true
schema:
type: string
enum:
- track.getInfo
- name: artist
in: query
required: false
schema:
type: string
- name: track
in: query
required: false
schema:
type: string
- name: mbid
in: query
required: false
schema:
type: string
- name: autocorrect
in: query
required: false
schema:
type: integer
enum: [0, 1]
- name: username
in: query
required: false
schema:
type: string
- name: api_key
in: query
required: true
schema:
type: string
- name: format
in: query
required: false
schema:
type: string
enum: [json, xml]
responses:
'200':
description: Track info response
content:
application/json:
schema:
$ref: '#/components/schemas/TrackInfoResponse'
track_search:
get:
operationId: track_search
summary: Search for a track
description: Search for a track by track name. Returns track matches sorted by relevance.
tags:
- Track
parameters:
- name: method
in: query
required: true
schema:
type: string
enum:
- track.search
- name: track
in: query
required: true
schema:
type: string
description: The track name to search for.
- name: artist
in: query
required: false
schema:
type: string
description: Narrow your results by specifying an artist.
- name: limit
in: query
required: false
schema:
type: integer
default: 30
- name: page
in: query
required: false
schema:
type: integer
default: 1
- name: api_key
in: query
required: true
schema:
type: string
- name: format
in: query
required: false
schema:
type: string
enum: [json, xml]
responses:
'200':
description: Track search results
content:
application/json:
schema:
$ref: '#/components/schemas/TrackSearchResponse'
track_getSimilar:
get:
operationId: track_getSimilar
summary: Get similar tracks
description: Returns similar tracks for this track based on listening data.
tags:
- Track
parameters:
- name: method
in: query
required: true
schema:
type: string
enum:
- track.getSimilar
- name: artist
in: query
required: false
schema:
type: string
- name: track
in: query
required: false
schema:
type: string
- name: mbid
in: query
required: false
schema:
type: string
- name: autocorrect
in: query
required: false
schema:
type: integer
enum: [0, 1]
- name: limit
in: query
required: false
schema:
type: integer
- name: api_key
in: query
required: true
schema:
type: string
- name: format
in: query
required: false
schema:
type: string
enum: [json, xml]
responses:
'200':
description: Similar tracks
content:
application/json:
schema:
$ref: '#/components/schemas/SimilarTracksResponse'
track_love:
post:
operationId: track_love
summary: Love a track
description: Love a track for a user profile. Requires authentication.
tags:
- Track
parameters:
- name: method
in: query
required: true
schema:
type: string
enum:
- track.love
- name: artist
in: query
required: true
schema:
type: string
- name: track
in: query
required: true
schema:
type: string
- name: api_key
in: query
required: true
schema:
type: string
- name: api_sig
in: query
required: true
schema:
type: string
- name: sk
in: query
required: true
schema:
type: string
responses:
'200':
description: Track loved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
security:
- SessionKey: []
user_getRecentTracks:
get:
operationId: user_getRecentTracks
summary: Get user recent tracks
description: Get a list of the recent tracks listened to by this user. Also includes the currently playing track with the nowplaying="true" attribute if the user is currently listening.
tags:
- User
parameters:
- name: method
in: query
required: true
schema:
type: string
enum:
- user.getRecentTracks
- name: user
in: query
required: true
schema:
type: string
description: The last.fm username to fetch the recent tracks of.
- name: api_key
in: query
required: true
schema:
type: string
- name: limit
in: query
required: false
schema:
type: integer
default: 50
maximum: 200
description: The number of results to fetch per page. Defaults to 50. Maximum is 200.
- name: page
in: query
required: false
schema:
type: integer
default: 1
- name: from
in: query
required: false
schema:
type: integer
description: Beginning timestamp of a range, UNIX timestamp format.
- name: to
in: query
required: false
schema:
type: integer
description: End timestamp of a range, UNIX timestamp format.
- name: extended
in: query
required: false
schema:
type: integer
enum: [0, 1]
description: Includes extended data in each artist, and whether the user has loved each track.
- name: format
in: query
required: false
schema:
type: string
enum: [json, xml]
responses:
'200':
description: Recent tracks list
content:
application/json:
schema:
$ref: '#/components/schemas/RecentTracksResponse'
user_getInfo:
get:
operationId: user_getInfo
summary: Get user info
description: Get information about a user profile.
tags:
- User
parameters:
- name: method
in: query
required: true
schema:
type: string
enum:
- user.getInfo
- name: user
in: query
required: true
schema:
type: string
description: The username to fetch the info for.
- name: api_key
in: query
required: true
schema:
type: string
- name: format
in: query
required: false
schema:
type: string
enum: [json, xml]
responses:
'200':
description: User profile information
content:
application/json:
schema:
$ref: '#/components/schemas/UserInfoResponse'
user_getTopArtists:
get:
operationId: user_getTopArtists
summary: Get user top artists
description: Get the top artists listened to by a user. You can stipulate a time period.
tags:
- User
parameters:
- name: method
in: query
required: true
schema:
type: string
enum:
- user.getTopArtists
- name: user
in: query
required: true
schema:
type: string
- name: period
in: query
required: false
schema:
type: string
enum: [overall, 7day, 1month, 3month, 6month, 12month]
description: The time period over which to retrieve top artists.
- name: limit
in: query
required: false
schema:
type: integer
default: 50
- name: page
in: query
required: false
schema:
type: integer
default: 1
- name: api_key
in: query
required: true
schema:
type: string
- name: format
in: query
required: false
schema:
type: string
enum: [json, xml]
responses:
'200':
description: User top artists
content:
application/json:
schema:
$ref: '#/components/schemas/TopArtistsResponse'
user_getTopTracks:
get:
operationId: user_getTopTracks
summary: Get user top tracks
description: Get the top tracks listened to by a user. You can stipulate a time period.
tags:
- User
parameters:
- name: method
in: query
required: true
schema:
type: string
enum:
- user.getTopTracks
- name: user
in: query
required: true
schema:
type: string
- name: period
in: query
required: false
schema:
type: string
enum: [overall, 7day, 1month, 3month, 6month, 12month]
- name: limit
in: query
required: false
schema:
type: integer
default: 50
- name: page
in: query
required: false
schema:
type: integer
default: 1
- name: api_key
in: query
required: true
schema:
type: string
- name: format
in: query
required: false
schema:
type: string
enum: [json, xml]
responses:
'200':
description: User top tracks
content:
application/json:
schema:
$ref: '#/components/schemas/TopTracksResponse'
user_getLovedTracks:
get:
operationId: user_getLovedTracks
summary: Get user loved tracks
description: A paginated list of all the tracks a user has loved.
tags:
- User
parameters:
- name: method
in: query
required: true
schema:
type: string
enum:
- user.getLovedTracks
- name: user
in: query
required: true
schema:
type: string
- name: limit
in: query
required: false
schema:
type: integer
default: 50
- name: page
in: query
required: false
schema:
type: integer
default: 1
- name: api_key
in: query
required: true
schema:
type: string
- name: format
in: query
required: false
schema:
type: string
enum: [json, xml]
responses:
'200':
description: Loved tracks list
content:
application/json:
schema:
$ref: '#/components/schemas/LovedTracksResponse'
user_getFriends:
get:
operationId: user_getFriends
summary: Get user friends
description: Get a list of the user's friends on Last.fm.
tags:
- User
parameters:
- name: method
in: query
required: true
schema:
type: string
enum:
- user.getFriends
- name: user
in: query
required: true
schema:
type: string
- name: recenttracks
in: query
required: false
schema:
type: integer
enum: [0, 1]
description: Whether or not to include information about friends' recent listening.
- name: limit
in: query
required: false
schema:
type: integer
default: 50
- name: page
in: query
required: false
schema:
type: integer
default: 1
- name: api_key
in: query
required: true
schema:
type: string
- name: format
in: query
required: false
schema:
type: string
enum: [json, xml]
responses:
'200':
description: User friends list
content:
application/json:
schema:
$ref: '#/components/schemas/FriendsResponse'
chart_getTopArtists:
get:
operationId: chart_getTopArtists
summary: Get top artists chart
description: Get the top artists chart.
tags:
- Chart
parameters:
- name: method
in: query
required: true
schema:
type: string
enum:
- chart.getTopArtists
- name: page
in: query
required: false
schema:
type: integer
default: 1
- name: limit
in: query
required: false
schema:
type: integer
default: 50
- name: api_key
in: query
required: true
schema:
type: string
- name: format
in: query
required: false
schema:
type: string
enum: [json, xml]
responses:
'200':
description: Top artists chart
content:
application/json:
schema:
$ref: '#/components/schemas/ChartArtistsResponse'
chart_getTopTracks:
get:
operationId: chart_getTopTracks
summary: Get top tracks chart
description: Get the top tracks chart.
tags:
- Chart
parameters:
- name: method
in: query
required: true
schema:
type: string
enum:
- chart.getTopTracks
- name: page
in: query
required: false
schema:
type: integer
default: 1
- name: limit
in: query
required: false
schema:
type: integer
default: 50
- name: api_key
in: query
required: true
schema:
type: string
- name: format
in: query
required: false
schema:
type: string
enum: [json, xml]
responses:
'200':
description: Top tracks chart
content:
application/json:
schema:
$ref: '#/components/schemas/ChartTracksResponse'
chart_getTopTags:
get:
operationId: chart_getTopTags
summary: Get top tags chart
description: Get the top tags chart.
tags:
- Chart
parameters:
- name: method
in: query
required: true
schema:
type: string
enum:
- chart.getTopTags
- name: page
in: query
required: false
schema:
type: integer
default: 1
- name: limit
in: query
required: false
schema:
type: integer
default: 50
- name: api_key
in: query
required: true
schema:
type: string
- name: format
in: query
required: false
schema:
type: string
enum: [json, xml]
responses:
'200':
description: Top tags chart
content:
application/json:
sche
# --- truncated at 32 KB (64 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/last-fm/refs/heads/main/openapi/last-fm-openapi.yml