Last.fm — Tool Reference
Explore listening history, top charts, genre tags, and similar listeners on Last.fm
Your AI assistant discovers and invokes these tools through the
MCP Server's meta tools —
it calls execute_tool with the tool name and arguments below.
# artist_get_top_tags read
Get the top Last.fm tags for an artist.
| Parameter | Type | Required | Description |
|---|---|---|---|
artist | string | Yes | Artist name. |
username | string | null | No | Include this user's tag context if supported. |
Parameter schema (JSON)
{
"properties": {
"artist": {
"description": "Artist name.",
"title": "Artist",
"type": "string"
},
"username": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Include this user's tag context if supported.",
"title": "Username"
}
},
"required": [
"artist"
],
"title": "ArtistGetTopTagsParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"Tag": {
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Count"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Url"
}
},
"required": [
"name"
],
"title": "Tag",
"type": "object"
}
},
"properties": {
"success": {
"title": "Success",
"type": "boolean"
},
"tags": {
"items": {
"$ref": "#/$defs/Tag"
},
"title": "Tags",
"type": "array"
}
},
"required": [
"success",
"tags"
],
"title": "ArtistGetTopTagsResult",
"type": "object"
} # get_album_info read
Get Last.fm album metadata, tracklist, tags, and optional user playcount.
| Parameter | Type | Required | Description |
|---|---|---|---|
artist | string | Yes | Artist name. |
album | string | Yes | Album name. |
username | string | null | No | Include this user's playcount for the album. Defaults to configured user. |
Parameter schema (JSON)
{
"properties": {
"artist": {
"description": "Artist name.",
"title": "Artist",
"type": "string"
},
"album": {
"description": "Album name.",
"title": "Album",
"type": "string"
},
"username": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Include this user's playcount for the album. Defaults to configured user.",
"title": "Username"
}
},
"required": [
"artist",
"album"
],
"title": "GetAlbumInfoParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"AlbumDetail": {
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"artist": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Artist"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Url"
},
"mbid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "MusicBrainz Identifier. May be null when Last.fm does not provide a MusicBrainz match.",
"title": "Mbid"
},
"playcount": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Playcount"
},
"user_playcount": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "User Playcount"
},
"listeners": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Listeners"
},
"tracks": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/AlbumTrackEntry"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Tracks"
},
"tags": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Tags"
}
},
"required": [
"name"
],
"title": "AlbumDetail",
"type": "object"
},
"AlbumTrackEntry": {
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"artist": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Artist"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Url"
},
"mbid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "MusicBrainz Identifier. May be null when Last.fm does not provide a MusicBrainz match.",
"title": "Mbid"
},
"duration_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Duration Ms"
}
},
"required": [
"name"
],
"title": "AlbumTrackEntry",
"type": "object"
}
},
"properties": {
"success": {
"title": "Success",
"type": "boolean"
},
"album": {
"$ref": "#/$defs/AlbumDetail"
}
},
"required": [
"success",
"album"
],
"title": "GetAlbumInfoResult",
"type": "object"
} # get_artist_info read
Get Last.fm artist metadata, tags, similar artists, and optional user playcount.
| Parameter | Type | Required | Description |
|---|---|---|---|
artist | string | Yes | Artist name. |
username | string | null | No | Include this user's playcount for the artist. Defaults to configured user. |
Parameter schema (JSON)
{
"properties": {
"artist": {
"description": "Artist name.",
"title": "Artist",
"type": "string"
},
"username": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Include this user's playcount for the artist. Defaults to configured user.",
"title": "Username"
}
},
"required": [
"artist"
],
"title": "GetArtistInfoParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"ArtistDetail": {
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Url"
},
"mbid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "MusicBrainz Identifier. May be null when Last.fm does not provide a MusicBrainz match.",
"title": "Mbid"
},
"playcount": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Playcount"
},
"user_playcount": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "User Playcount"
},
"listeners": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Listeners"
},
"bio_summary": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Bio Summary"
},
"tags": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Tags"
},
"similar": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Similar"
}
},
"required": [
"name"
],
"title": "ArtistDetail",
"type": "object"
}
},
"properties": {
"success": {
"title": "Success",
"type": "boolean"
},
"artist": {
"$ref": "#/$defs/ArtistDetail"
}
},
"required": [
"success",
"artist"
],
"title": "GetArtistInfoResult",
"type": "object"
} # get_artist_similar read
Get artists similar to a Last.fm artist.
| Parameter | Type | Required | Description |
|---|---|---|---|
artist | string | Yes | Artist name. |
limit | integer | No | Maximum number of similar artists to return. Default: 50 |
Parameter schema (JSON)
{
"properties": {
"artist": {
"description": "Artist name.",
"title": "Artist",
"type": "string"
},
"limit": {
"default": 50,
"description": "Maximum number of similar artists to return.",
"maximum": 100,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
"required": [
"artist"
],
"title": "GetArtistSimilarParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"ArtistSimilarityEntry": {
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Url"
},
"mbid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "MusicBrainz Identifier. May be null when Last.fm does not provide a MusicBrainz match.",
"title": "Mbid"
},
"match": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Match"
},
"listeners": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Listeners"
}
},
"required": [
"name"
],
"title": "ArtistSimilarityEntry",
"type": "object"
}
},
"properties": {
"success": {
"title": "Success",
"type": "boolean"
},
"artists": {
"items": {
"$ref": "#/$defs/ArtistSimilarityEntry"
},
"title": "Artists",
"type": "array"
}
},
"required": [
"success",
"artists"
],
"title": "GetArtistSimilarResult",
"type": "object"
} # get_listening_summary read
Summarize a Last.fm user's listening span, first and latest scrobbles, total playcount, and average scrobbles per day. Pass `timezone` (IANA name) to render the summary's `*_iso` fields in that zone.
Full description
Summarize a Last.fm user's listening span, first and latest scrobbles, total playcount, and average scrobbles per day. All `*_timestamp` fields are Unix epoch seconds (UTC) and are the source of truth. The paired `*_iso` fields are self-describing ISO 8601 strings rendered in the requested `timezone` (default `UTC`).
| Parameter | Type | Required | Description |
|---|---|---|---|
username | string | null | No | Last.fm username to query. Defaults to the configured user. |
timezone | string | No | IANA timezone name (e.g. 'America/Los_Angeles', 'Asia/Tokyo') used to render `date_iso` on returned tracks. Defaults to 'UTC'. The epoch `timestamp` field is unaffected and always represents UTC seconds. Default: "UTC" |
Parameter schema (JSON)
{
"properties": {
"username": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Last.fm username to query. Defaults to the configured user.",
"title": "Username"
},
"timezone": {
"default": "UTC",
"description": "IANA timezone name (e.g. 'America/Los_Angeles', 'Asia/Tokyo') used to render `date_iso` on returned tracks. Defaults to 'UTC'. The epoch `timestamp` field is unaffected and always represents UTC seconds.",
"title": "Timezone",
"type": "string"
}
},
"title": "GetListeningSummaryParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"ListeningSummary": {
"properties": {
"username": {
"title": "Username",
"type": "string"
},
"total_playcount": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Total Playcount"
},
"registered_timestamp": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Unix epoch seconds (UTC) of when the user registered with Last.fm.",
"title": "Registered Timestamp"
},
"registered_iso": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ISO 8601 timestamp with offset, rendered in the response's `timezone`.",
"title": "Registered Iso"
},
"first_scrobble_timestamp": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Unix epoch seconds (UTC) of the user's earliest known scrobble.",
"title": "First Scrobble Timestamp"
},
"first_scrobble_iso": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ISO 8601 timestamp with offset, rendered in the response's `timezone`.",
"title": "First Scrobble Iso"
},
"last_scrobble_timestamp": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Unix epoch seconds (UTC) of the user's most recent scrobble.",
"title": "Last Scrobble Timestamp"
},
"last_scrobble_iso": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ISO 8601 timestamp with offset, rendered in the response's `timezone`.",
"title": "Last Scrobble Iso"
},
"days_since_first_scrobble": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Days Since First Scrobble"
},
"days_since_last_scrobble": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Days Since Last Scrobble"
},
"avg_scrobbles_per_day": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Avg Scrobbles Per Day"
},
"active_span_days": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Active Span Days"
}
},
"required": [
"username"
],
"title": "ListeningSummary",
"type": "object"
}
},
"properties": {
"success": {
"title": "Success",
"type": "boolean"
},
"summary": {
"$ref": "#/$defs/ListeningSummary"
},
"timezone": {
"default": "UTC",
"description": "IANA timezone in which the summary's `*_iso` timestamp fields were rendered.",
"title": "Timezone",
"type": "string"
}
},
"required": [
"success",
"summary"
],
"title": "GetListeningSummaryResult",
"type": "object"
} # get_loved_tracks read
Get the user's loved Last.fm tracks. Pass `timezone` (IANA name) to render `date_iso` in that zone.
Full description
Get the user's loved Last.fm tracks. Each track carries a `timestamp` (Unix epoch seconds, UTC) and a `date_iso` string rendered in the requested `timezone` (default `UTC`). The ISO string includes the UTC offset, so it is unambiguous on its own.
| Parameter | Type | Required | Description |
|---|---|---|---|
username | string | null | No | Last.fm username to query. Defaults to the configured user. |
limit | integer | No | Maximum number of loved tracks to return. Default: 50 |
page | integer | No | Result page to fetch. Default: 1 |
timezone | string | No | IANA timezone name (e.g. 'America/Los_Angeles', 'Asia/Tokyo') used to render `date_iso` on returned tracks. Defaults to 'UTC'. The epoch `timestamp` field is unaffected and always represents UTC seconds. Default: "UTC" |
Parameter schema (JSON)
{
"properties": {
"username": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Last.fm username to query. Defaults to the configured user.",
"title": "Username"
},
"limit": {
"default": 50,
"description": "Maximum number of loved tracks to return.",
"maximum": 200,
"minimum": 1,
"title": "Limit",
"type": "integer"
},
"page": {
"default": 1,
"description": "Result page to fetch.",
"minimum": 1,
"title": "Page",
"type": "integer"
},
"timezone": {
"default": "UTC",
"description": "IANA timezone name (e.g. 'America/Los_Angeles', 'Asia/Tokyo') used to render `date_iso` on returned tracks. Defaults to 'UTC'. The epoch `timestamp` field is unaffected and always represents UTC seconds.",
"title": "Timezone",
"type": "string"
}
},
"title": "GetLovedTracksParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"DataWindow": {
"properties": {
"page": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Page"
},
"per_page": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Per Page"
},
"total_pages": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Total Pages"
},
"total": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Total"
}
},
"title": "DataWindow",
"type": "object"
},
"LovedTrack": {
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"artist": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Artist"
},
"album": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Album"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Url"
},
"mbid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "MusicBrainz Identifier. May be null when Last.fm does not provide a MusicBrainz match.",
"title": "Mbid"
},
"loved": {
"default": true,
"title": "Loved",
"type": "boolean"
},
"timestamp": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Unix epoch seconds (UTC). Source of truth for time-of-day analysis.",
"title": "Timestamp"
},
"date_iso": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ISO 8601 timestamp with offset, rendered in the response's `timezone` (defaults to UTC). Self-describing — the offset is part of the value.",
"title": "Date Iso"
}
},
"required": [
"name"
],
"title": "LovedTrack",
"type": "object"
}
},
"properties": {
"success": {
"title": "Success",
"type": "boolean"
},
"username": {
"title": "Username",
"type": "string"
},
"tracks": {
"items": {
"$ref": "#/$defs/LovedTrack"
},
"title": "Tracks",
"type": "array"
},
"timezone": {
"default": "UTC",
"description": "IANA timezone in which `date_iso` on each track was rendered.",
"title": "Timezone",
"type": "string"
},
"data_window": {
"anyOf": [
{
"$ref": "#/$defs/DataWindow"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"success",
"username",
"tracks"
],
"title": "GetLovedTracksResult",
"type": "object"
} # get_recent_tracks read
Get the user's most recent Last.fm scrobbles with timestamps and track metadata. Pass `timezone` (IANA name) to render `date_iso` in that zone for time-of-day analysis.
Full description
Get the user's most recent Last.fm scrobbles with timestamps and track metadata. Each track carries a `timestamp` (Unix epoch seconds, UTC) and a `date_iso` string rendered in the requested `timezone` (default `UTC`). The ISO string includes the UTC offset, so it is unambiguous on its own.
| Parameter | Type | Required | Description |
|---|---|---|---|
username | string | null | No | Last.fm username to query. Defaults to the configured user. |
limit | integer | No | Maximum number of scrobbles to return. Large windows may require multiple calls. Default: 50 |
page | integer | No | Result page to fetch. Default: 1 |
from_timestamp | integer | null | No | Only include scrobbles at or after this Unix timestamp. Note: this is UTC epoch seconds — local-day boundaries must be converted to UTC by the caller (e.g. start-of-day in 'America/Los_Angeles' becomes a different UTC epoch than start-of-day in 'Asia/Tokyo'). |
to_timestamp | integer | null | No | Only include scrobbles at or before this Unix timestamp. Note: this is UTC epoch seconds — local-day boundaries must be converted to UTC by the caller (e.g. start-of-day in 'America/Los_Angeles' becomes a different UTC epoch than start-of-day in 'Asia/Tokyo'). |
timezone | string | No | IANA timezone name (e.g. 'America/Los_Angeles', 'Asia/Tokyo') used to render `date_iso` on returned tracks. Defaults to 'UTC'. The epoch `timestamp` field is unaffected and always represents UTC seconds. Default: "UTC" |
Parameter schema (JSON)
{
"properties": {
"username": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Last.fm username to query. Defaults to the configured user.",
"title": "Username"
},
"limit": {
"default": 50,
"description": "Maximum number of scrobbles to return. Large windows may require multiple calls.",
"maximum": 200,
"minimum": 1,
"title": "Limit",
"type": "integer"
},
"page": {
"default": 1,
"description": "Result page to fetch.",
"minimum": 1,
"title": "Page",
"type": "integer"
},
"from_timestamp": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Only include scrobbles at or after this Unix timestamp. Note: this is UTC epoch seconds — local-day boundaries must be converted to UTC by the caller (e.g. start-of-day in 'America/Los_Angeles' becomes a different UTC epoch than start-of-day in 'Asia/Tokyo').",
"title": "From Timestamp"
},
"to_timestamp": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Only include scrobbles at or before this Unix timestamp. Note: this is UTC epoch seconds — local-day boundaries must be converted to UTC by the caller (e.g. start-of-day in 'America/Los_Angeles' becomes a different UTC epoch than start-of-day in 'Asia/Tokyo').",
"title": "To Timestamp"
},
"timezone": {
"default": "UTC",
"description": "IANA timezone name (e.g. 'America/Los_Angeles', 'Asia/Tokyo') used to render `date_iso` on returned tracks. Defaults to 'UTC'. The epoch `timestamp` field is unaffected and always represents UTC seconds.",
"title": "Timezone",
"type": "string"
}
},
"title": "GetRecentTracksParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"DataWindow": {
"properties": {
"page": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Page"
},
"per_page": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Per Page"
},
"total_pages": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Total Pages"
},
"total": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Total"
}
},
"title": "DataWindow",
"type": "object"
},
"RecentTrack": {
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"artist": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Artist"
},
"album": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Album"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Url"
},
"mbid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "MusicBrainz Identifier. May be null when Last.fm does not provide a MusicBrainz match.",
"title": "Mbid"
},
"loved": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"title": "Loved"
},
"now_playing": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"title": "Now Playing"
},
"timestamp": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Unix epoch seconds (UTC). Source of truth for time-of-day analysis.",
"title": "Timestamp"
},
"date_iso": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ISO 8601 timestamp with offset, rendered in the response's `timezone` (defaults to UTC). Self-describing — the offset is part of the value, so the string is safe to display without separately tracking the zone.",
"title": "Date Iso"
}
},
"required": [
"name"
],
"title": "RecentTrack",
"type": "object"
}
},
"properties": {
"success": {
"title": "Success",
"type": "boolean"
},
"username": {
"title": "Username",
"type": "string"
},
"tracks": {
"items": {
"$ref": "#/$defs/RecentTrack"
},
"title": "Tracks",
"type": "array"
},
"timezone": {
"default": "UTC",
"description": "IANA timezone in which `date_iso` on each track was rendered.",
"title": "Timezone",
"type": "string"
},
"data_window": {
"anyOf": [
{
"$ref": "#/$defs/DataWindow"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"success",
"username",
"tracks"
],
"title": "GetRecentTracksResult",
"type": "object"
} # get_tag_top_artists read
Get the top artists for a Last.fm tag.
| Parameter | Type | Required | Description |
|---|---|---|---|
tag | string | Yes | Tag or genre name. |
limit | integer | No | Maximum number of artists to return. Default: 50 |
Parameter schema (JSON)
{
"properties": {
"tag": {
"description": "Tag or genre name.",
"title": "Tag",
"type": "string"
},
"limit": {
"default": 50,
"description": "Maximum number of artists to return.",
"maximum": 100,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
"required": [
"tag"
],
"title": "GetTagTopArtistsParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"TagTopArtistEntry": {
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Url"
},
"mbid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "MusicBrainz Identifier. May be null when Last.fm does not provide a MusicBrainz match.",
"title": "Mbid"
}
},
"required": [
"name"
],
"title": "TagTopArtistEntry",
"type": "object"
}
},
"properties": {
"success": {
"title": "Success",
"type": "boolean"
},
"artists": {
"items": {
"$ref": "#/$defs/TagTopArtistEntry"
},
"title": "Artists",
"type": "array"
}
},
"required": [
"success",
"artists"
],
"title": "GetTagTopArtistsResult",
"type": "object"
} # get_top_albums read
Get the user's most-listened Last.fm albums for a fixed period.
| Parameter | Type | Required | Description |
|---|---|---|---|
username | string | null | No | Last.fm username to query. Defaults to the configured user. |
period | "overall" | "7day" | "1month" | "3month" | "6month" | "12month" | No | Chart period: overall, 7day, 1month, 3month, 6month, or 12month. Default: "overall" |
limit | integer | No | Maximum number of results to return. Default: 50 |
page | integer | No | Result page to fetch. Default: 1 |
Parameter schema (JSON)
{
"properties": {
"username": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Last.fm username to query. Defaults to the configured user.",
"title": "Username"
},
"period": {
"default": "overall",
"description": "Chart period: overall, 7day, 1month, 3month, 6month, or 12month.",
"enum": [
"overall",
"7day",
"1month",
"3month",
"6month",
"12month"
],
"title": "Period",
"type": "string"
},
"limit": {
"default": 50,
"description": "Maximum number of results to return.",
"maximum": 200,
"minimum": 1,
"title": "Limit",
"type": "integer"
},
"page": {
"default": 1,
"description": "Result page to fetch.",
"minimum": 1,
"title": "Page",
"type": "integer"
}
},
"title": "TopChartParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"AlbumChartEntry": {
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"artist": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Artist"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Url"
},
"mbid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "MusicBrainz Identifier. May be null when Last.fm does not provide a MusicBrainz match.",
"title": "Mbid"
},
"playcount": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Playcount"
}
},
"required": [
"name"
],
"title": "AlbumChartEntry",
"type": "object"
},
"DataWindow": {
"properties": {
"page": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Page"
},
"per_page": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Per Page"
},
"total_pages": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Total Pages"
},
"total": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Total"
}
},
"title": "DataWindow",
"type": "object"
}
},
"properties": {
"success": {
"title": "Success",
"type": "boolean"
},
"username": {
"title": "Username",
"type": "string"
},
"albums": {
"items": {
"$ref": "#/$defs/AlbumChartEntry"
},
"title": "Albums",
"type": "array"
},
"data_window": {
"anyOf": [
{
"$ref": "#/$defs/DataWindow"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"success",
"username",
"albums"
],
"title": "GetTopAlbumsResult",
"type": "object"
} # get_top_artists read
Get the user's most-listened Last.fm artists for a fixed period.
| Parameter | Type | Required | Description |
|---|---|---|---|
username | string | null | No | Last.fm username to query. Defaults to the configured user. |
period | "overall" | "7day" | "1month" | "3month" | "6month" | "12month" | No | Chart period: overall, 7day, 1month, 3month, 6month, or 12month. Default: "overall" |
limit | integer | No | Maximum number of results to return. Default: 50 |
page | integer | No | Result page to fetch. Default: 1 |
Parameter schema (JSON)
{
"properties": {
"username": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Last.fm username to query. Defaults to the configured user.",
"title": "Username"
},
"period": {
"default": "overall",
"description": "Chart period: overall, 7day, 1month, 3month, 6month, or 12month.",
"enum": [
"overall",
"7day",
"1month",
"3month",
"6month",
"12month"
],
"title": "Period",
"type": "string"
},
"limit": {
"default": 50,
"description": "Maximum number of results to return.",
"maximum": 200,
"minimum": 1,
"title": "Limit",
"type": "integer"
},
"page": {
"default": 1,
"description": "Result page to fetch.",
"minimum": 1,
"title": "Page",
"type": "integer"
}
},
"title": "TopChartParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"ArtistChartEntry": {
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Url"
},
"mbid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "MusicBrainz Identifier. May be null when Last.fm does not provide a MusicBrainz match.",
"title": "Mbid"
},
"playcount": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Playcount"
},
"listeners": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Listeners"
}
},
"required": [
"name"
],
"title": "ArtistChartEntry",
"type": "object"
},
"DataWindow": {
"properties": {
"page": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Page"
},
"per_page": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Per Page"
},
"total_pages": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Total Pages"
},
"total": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Total"
}
},
"title": "DataWindow",
"type": "object"
}
},
"properties": {
"success": {
"title": "Success",
"type": "boolean"
},
"username": {
"title": "Username",
"type": "string"
},
"artists": {
"items": {
"$ref": "#/$defs/ArtistChartEntry"
},
"title": "Artists",
"type": "array"
},
"data_window": {
"anyOf": [
{
"$ref": "#/$defs/DataWindow"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"success",
"username",
"artists"
],
"title": "GetTopArtistsResult",
"type": "object"
} # get_top_tracks read
Get the user's most-listened Last.fm tracks for a fixed period.
| Parameter | Type | Required | Description |
|---|---|---|---|
username | string | null | No | Last.fm username to query. Defaults to the configured user. |
period | "overall" | "7day" | "1month" | "3month" | "6month" | "12month" | No | Chart period: overall, 7day, 1month, 3month, 6month, or 12month. Default: "overall" |
limit | integer | No | Maximum number of results to return. Default: 50 |
page | integer | No | Result page to fetch. Default: 1 |
Parameter schema (JSON)
{
"properties": {
"username": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Last.fm username to query. Defaults to the configured user.",
"title": "Username"
},
"period": {
"default": "overall",
"description": "Chart period: overall, 7day, 1month, 3month, 6month, or 12month.",
"enum": [
"overall",
"7day",
"1month",
"3month",
"6month",
"12month"
],
"title": "Period",
"type": "string"
},
"limit": {
"default": 50,
"description": "Maximum number of results to return.",
"maximum": 200,
"minimum": 1,
"title": "Limit",
"type": "integer"
},
"page": {
"default": 1,
"description": "Result page to fetch.",
"minimum": 1,
"title": "Page",
"type": "integer"
}
},
"title": "TopChartParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"DataWindow": {
"properties": {
"page": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Page"
},
"per_page": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Per Page"
},
"total_pages": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Total Pages"
},
"total": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Total"
}
},
"title": "DataWindow",
"type": "object"
},
"TrackChartEntry": {
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"artist": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Artist"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Url"
},
"mbid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "MusicBrainz Identifier. May be null when Last.fm does not provide a MusicBrainz match.",
"title": "Mbid"
},
"playcount": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Playcount"
}
},
"required": [
"name"
],
"title": "TrackChartEntry",
"type": "object"
}
},
"properties": {
"success": {
"title": "Success",
"type": "boolean"
},
"username": {
"title": "Username",
"type": "string"
},
"tracks": {
"items": {
"$ref": "#/$defs/TrackChartEntry"
},
"title": "Tracks",
"type": "array"
},
"data_window": {
"anyOf": [
{
"$ref": "#/$defs/DataWindow"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"success",
"username",
"tracks"
],
"title": "GetTopTracksResult",
"type": "object"
} # get_track_info read
Get Last.fm track metadata, tags, duration, and optional user stats.
| Parameter | Type | Required | Description |
|---|---|---|---|
artist | string | Yes | Artist name. |
track | string | Yes | Track name. |
username | string | null | No | Include this user's playcount/loved status for the track. Defaults to configured user. |
Parameter schema (JSON)
{
"properties": {
"artist": {
"description": "Artist name.",
"title": "Artist",
"type": "string"
},
"track": {
"description": "Track name.",
"title": "Track",
"type": "string"
},
"username": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Include this user's playcount/loved status for the track. Defaults to configured user.",
"title": "Username"
}
},
"required": [
"artist",
"track"
],
"title": "GetTrackInfoParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"TrackDetail": {
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"artist": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Artist"
},
"album": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Album"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Url"
},
"mbid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "MusicBrainz Identifier. May be null when Last.fm does not provide a MusicBrainz match.",
"title": "Mbid"
},
"playcount": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Playcount"
},
"user_playcount": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "User Playcount"
},
"listeners": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Listeners"
},
"duration_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Duration Ms"
},
"loved": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"title": "Loved"
},
"tags": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Tags"
}
},
"required": [
"name"
],
"title": "TrackDetail",
"type": "object"
}
},
"properties": {
"success": {
"title": "Success",
"type": "boolean"
},
"track": {
"$ref": "#/$defs/TrackDetail"
}
},
"required": [
"success",
"track"
],
"title": "GetTrackInfoResult",
"type": "object"
} # get_track_similar read
Get tracks similar to a Last.fm track.
| Parameter | Type | Required | Description |
|---|---|---|---|
artist | string | Yes | Artist name. |
track | string | Yes | Track name. |
limit | integer | No | Maximum number of similar tracks to return. Default: 50 |
Parameter schema (JSON)
{
"properties": {
"artist": {
"description": "Artist name.",
"title": "Artist",
"type": "string"
},
"track": {
"description": "Track name.",
"title": "Track",
"type": "string"
},
"limit": {
"default": 50,
"description": "Maximum number of similar tracks to return.",
"maximum": 100,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
"required": [
"artist",
"track"
],
"title": "GetTrackSimilarParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"TrackSimilarityEntry": {
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"artist": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Artist"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Url"
},
"mbid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "MusicBrainz Identifier. May be null when Last.fm does not provide a MusicBrainz match.",
"title": "Mbid"
},
"match": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Match"
},
"playcount": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Playcount"
},
"duration_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Duration Ms"
}
},
"required": [
"name"
],
"title": "TrackSimilarityEntry",
"type": "object"
}
},
"properties": {
"success": {
"title": "Success",
"type": "boolean"
},
"tracks": {
"items": {
"$ref": "#/$defs/TrackSimilarityEntry"
},
"title": "Tracks",
"type": "array"
}
},
"required": [
"success",
"tracks"
],
"title": "GetTrackSimilarResult",
"type": "object"
} # get_user_info read
Get Last.fm profile details for a user. Pass `timezone` (IANA name) to render `registered_iso` in that zone.
Full description
Get Last.fm profile details for a user. `registered_timestamp` is Unix epoch seconds (UTC); `registered_iso` is the same value rendered as a self-describing ISO 8601 string in the requested `timezone` (default `UTC`).
| Parameter | Type | Required | Description |
|---|---|---|---|
username | string | null | No | Last.fm username to query. Defaults to the configured user. |
timezone | string | No | IANA timezone name (e.g. 'America/Los_Angeles', 'Asia/Tokyo') used to render `date_iso` on returned tracks. Defaults to 'UTC'. The epoch `timestamp` field is unaffected and always represents UTC seconds. Default: "UTC" |
Parameter schema (JSON)
{
"properties": {
"username": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Last.fm username to query. Defaults to the configured user.",
"title": "Username"
},
"timezone": {
"default": "UTC",
"description": "IANA timezone name (e.g. 'America/Los_Angeles', 'Asia/Tokyo') used to render `date_iso` on returned tracks. Defaults to 'UTC'. The epoch `timestamp` field is unaffected and always represents UTC seconds.",
"title": "Timezone",
"type": "string"
}
},
"title": "GetUserInfoParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"UserInfo": {
"properties": {
"username": {
"title": "Username",
"type": "string"
},
"realname": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Realname"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Url"
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Country"
},
"playcount": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Playcount"
},
"playlists": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Playlists"
},
"registered_timestamp": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Unix epoch seconds (UTC) of when the user registered with Last.fm.",
"title": "Registered Timestamp"
},
"registered_iso": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ISO 8601 timestamp with offset for when the user registered, rendered in the response's `timezone` (defaults to UTC). Self-describing — the offset is part of the value.",
"title": "Registered Iso"
}
},
"required": [
"username"
],
"title": "UserInfo",
"type": "object"
}
},
"properties": {
"success": {
"title": "Success",
"type": "boolean"
},
"user": {
"$ref": "#/$defs/UserInfo"
},
"timezone": {
"default": "UTC",
"description": "IANA timezone in which `registered_iso` on the user was rendered.",
"title": "Timezone",
"type": "string"
}
},
"required": [
"success",
"user"
],
"title": "GetUserInfoResult",
"type": "object"
} # get_user_neighbours read
Get Last.fm users with similar music taste from the public neighbours page.
| Parameter | Type | Required | Description |
|---|---|---|---|
username | string | null | No | Last.fm username to query. Defaults to the configured user. |
limit | integer | No | Maximum neighbours to return from the page. Default: 50 |
page | integer | No | Neighbours page to fetch. Default: 1 |
Parameter schema (JSON)
{
"properties": {
"username": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Last.fm username to query. Defaults to the configured user.",
"title": "Username"
},
"limit": {
"default": 50,
"description": "Maximum neighbours to return from the page.",
"maximum": 50,
"minimum": 1,
"title": "Limit",
"type": "integer"
},
"page": {
"default": 1,
"description": "Neighbours page to fetch.",
"minimum": 1,
"title": "Page",
"type": "integer"
}
},
"title": "GetUserNeighboursParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"Neighbour": {
"properties": {
"username": {
"title": "Username",
"type": "string"
},
"profile_url": {
"title": "Profile Url",
"type": "string"
},
"avatar_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Avatar Url"
},
"shared_artists": {
"items": {
"type": "string"
},
"title": "Shared Artists",
"type": "array"
}
},
"required": [
"username",
"profile_url"
],
"title": "Neighbour",
"type": "object"
}
},
"properties": {
"success": {
"title": "Success",
"type": "boolean"
},
"username": {
"title": "Username",
"type": "string"
},
"neighbours": {
"items": {
"$ref": "#/$defs/Neighbour"
},
"title": "Neighbours",
"type": "array"
}
},
"required": [
"success",
"username",
"neighbours"
],
"title": "GetUserNeighboursResult",
"type": "object"
} # get_user_top_tags read
Get the user's most-used Last.fm tags.
| Parameter | Type | Required | Description |
|---|---|---|---|
username | string | null | No | Last.fm username to query. Defaults to the configured user. |
limit | integer | No | Maximum number of user tags to return. Returns an empty list if the user has no public/user-created tags. Default: 50 |
Parameter schema (JSON)
{
"properties": {
"username": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Last.fm username to query. Defaults to the configured user.",
"title": "Username"
},
"limit": {
"default": 50,
"description": "Maximum number of user tags to return. Returns an empty list if the user has no public/user-created tags.",
"maximum": 100,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
"title": "GetUserTopTagsParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"Tag": {
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Count"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Url"
}
},
"required": [
"name"
],
"title": "Tag",
"type": "object"
}
},
"properties": {
"success": {
"title": "Success",
"type": "boolean"
},
"username": {
"title": "Username",
"type": "string"
},
"tags": {
"items": {
"$ref": "#/$defs/Tag"
},
"title": "Tags",
"type": "array"
}
},
"required": [
"success",
"username",
"tags"
],
"title": "GetUserTopTagsResult",
"type": "object"
} # get_weekly_chart read
Get one Last.fm weekly chart for an aligned week window.
Full description
Get one Last.fm weekly chart for an aligned week window. Last.fm weekly windows work best with Sunday 12:00 UTC boundaries. Start from an aligned timestamp, then add or subtract 604800-second steps to compute valid weekly windows. Use lastfm-get_listening_summary first_scrobble_timestamp as an anchor when choosing a user's historical range.
| Parameter | Type | Required | Description |
|---|---|---|---|
username | string | null | No | Last.fm username to query. Defaults to the configured user. |
chart_type | "artist" | "album" | "track" | Yes | Weekly chart type: artist, album, or track. |
from_timestamp | integer | Yes | Week start Unix epoch seconds (UTC). For best results, align to Last.fm weekly boundaries: Sunday 12:00 UTC, then add or subtract 604800-second steps. Use lastfm-get_listening_summary first_scrobble_timestamp as an anchor for a user's history. Note: this is UTC epoch seconds — local-day boundaries must be converted to UTC by the caller (e.g. start-of-day in 'America/Los_Angeles' becomes a different UTC epoch than start-of-day in 'Asia/Tokyo'). |
to_timestamp | integer | Yes | Week end Unix epoch seconds (UTC). Use the aligned from_timestamp plus 604800 seconds for one Last.fm weekly window. Note: this is UTC epoch seconds — local-day boundaries must be converted to UTC by the caller (e.g. start-of-day in 'America/Los_Angeles' becomes a different UTC epoch than start-of-day in 'Asia/Tokyo'). |
limit | integer | No | Maximum chart entries to return. Default: 50 |
Parameter schema (JSON)
{
"properties": {
"username": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Last.fm username to query. Defaults to the configured user.",
"title": "Username"
},
"chart_type": {
"description": "Weekly chart type: artist, album, or track.",
"enum": [
"artist",
"album",
"track"
],
"title": "Chart Type",
"type": "string"
},
"from_timestamp": {
"description": "Week start Unix epoch seconds (UTC). For best results, align to Last.fm weekly boundaries: Sunday 12:00 UTC, then add or subtract 604800-second steps. Use lastfm-get_listening_summary first_scrobble_timestamp as an anchor for a user's history. Note: this is UTC epoch seconds — local-day boundaries must be converted to UTC by the caller (e.g. start-of-day in 'America/Los_Angeles' becomes a different UTC epoch than start-of-day in 'Asia/Tokyo').",
"title": "From Timestamp",
"type": "integer"
},
"to_timestamp": {
"description": "Week end Unix epoch seconds (UTC). Use the aligned from_timestamp plus 604800 seconds for one Last.fm weekly window. Note: this is UTC epoch seconds — local-day boundaries must be converted to UTC by the caller (e.g. start-of-day in 'America/Los_Angeles' becomes a different UTC epoch than start-of-day in 'Asia/Tokyo').",
"title": "To Timestamp",
"type": "integer"
},
"limit": {
"default": 50,
"description": "Maximum chart entries to return.",
"maximum": 200,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
"required": [
"chart_type",
"from_timestamp",
"to_timestamp"
],
"title": "GetWeeklyChartParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"AlbumChartEntry": {
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"artist": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Artist"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Url"
},
"mbid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "MusicBrainz Identifier. May be null when Last.fm does not provide a MusicBrainz match.",
"title": "Mbid"
},
"playcount": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Playcount"
}
},
"required": [
"name"
],
"title": "AlbumChartEntry",
"type": "object"
},
"ArtistChartEntry": {
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Url"
},
"mbid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "MusicBrainz Identifier. May be null when Last.fm does not provide a MusicBrainz match.",
"title": "Mbid"
},
"playcount": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Playcount"
},
"listeners": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Listeners"
}
},
"required": [
"name"
],
"title": "ArtistChartEntry",
"type": "object"
},
"TrackChartEntry": {
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"artist": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Artist"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Url"
},
"mbid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "MusicBrainz Identifier. May be null when Last.fm does not provide a MusicBrainz match.",
"title": "Mbid"
},
"playcount": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Playcount"
}
},
"required": [
"name"
],
"title": "TrackChartEntry",
"type": "object"
}
},
"properties": {
"success": {
"title": "Success",
"type": "boolean"
},
"username": {
"title": "Username",
"type": "string"
},
"chart_type": {
"enum": [
"artist",
"album",
"track"
],
"title": "Chart Type",
"type": "string"
},
"from_timestamp": {
"description": "Week start Unix epoch seconds (UTC), echoed from the request.",
"title": "From Timestamp",
"type": "integer"
},
"to_timestamp": {
"description": "Week end Unix epoch seconds (UTC), echoed from the request.",
"title": "To Timestamp",
"type": "integer"
},
"artists": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/ArtistChartEntry"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Artists"
},
"albums": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/AlbumChartEntry"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Albums"
},
"tracks": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/TrackChartEntry"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Tracks"
}
},
"required": [
"success",
"username",
"chart_type",
"from_timestamp",
"to_timestamp"
],
"title": "GetWeeklyChartResult",
"type": "object"
} # tag_get_info read
Get Last.fm metadata for a tag, including reach, total taggings, and wiki text.
| Parameter | Type | Required | Description |
|---|---|---|---|
tag | string | Yes | Tag or genre name. |
Parameter schema (JSON)
{
"properties": {
"tag": {
"description": "Tag or genre name.",
"title": "Tag",
"type": "string"
}
},
"required": [
"tag"
],
"title": "TagGetInfoParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"TagInfo": {
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"total": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Total"
},
"reach": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Reach"
},
"wiki_summary": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Wiki Summary"
},
"wiki_content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Wiki Content"
}
},
"required": [
"name"
],
"title": "TagInfo",
"type": "object"
}
},
"properties": {
"success": {
"title": "Success",
"type": "boolean"
},
"tag": {
"$ref": "#/$defs/TagInfo"
}
},
"required": [
"success",
"tag"
],
"title": "TagGetInfoResult",
"type": "object"
} # tag_top_albums read
Get the top Last.fm albums for a tag.
| Parameter | Type | Required | Description |
|---|---|---|---|
tag | string | Yes | Tag or genre name. |
limit | integer | No | Maximum number of albums to return. Default: 50 |
page | integer | No | Result page to fetch. Default: 1 |
Parameter schema (JSON)
{
"properties": {
"tag": {
"description": "Tag or genre name.",
"title": "Tag",
"type": "string"
},
"limit": {
"default": 50,
"description": "Maximum number of albums to return.",
"maximum": 100,
"minimum": 1,
"title": "Limit",
"type": "integer"
},
"page": {
"default": 1,
"description": "Result page to fetch.",
"minimum": 1,
"title": "Page",
"type": "integer"
}
},
"required": [
"tag"
],
"title": "TagTopAlbumsParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"DataWindow": {
"properties": {
"page": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Page"
},
"per_page": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Per Page"
},
"total_pages": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Total Pages"
},
"total": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Total"
}
},
"title": "DataWindow",
"type": "object"
},
"TagTopAlbumEntry": {
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"artist": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Artist"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Url"
},
"mbid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "MusicBrainz Identifier. May be null when Last.fm does not provide a MusicBrainz match.",
"title": "Mbid"
}
},
"required": [
"name"
],
"title": "TagTopAlbumEntry",
"type": "object"
}
},
"properties": {
"success": {
"title": "Success",
"type": "boolean"
},
"albums": {
"items": {
"$ref": "#/$defs/TagTopAlbumEntry"
},
"title": "Albums",
"type": "array"
},
"data_window": {
"anyOf": [
{
"$ref": "#/$defs/DataWindow"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"success",
"albums"
],
"title": "TagTopAlbumsResult",
"type": "object"
} # tag_top_tracks read
Get the top Last.fm tracks for a tag.
| Parameter | Type | Required | Description |
|---|---|---|---|
tag | string | Yes | Tag or genre name. |
limit | integer | No | Maximum number of tracks to return. Default: 50 |
page | integer | No | Result page to fetch. Default: 1 |
Parameter schema (JSON)
{
"properties": {
"tag": {
"description": "Tag or genre name.",
"title": "Tag",
"type": "string"
},
"limit": {
"default": 50,
"description": "Maximum number of tracks to return.",
"maximum": 100,
"minimum": 1,
"title": "Limit",
"type": "integer"
},
"page": {
"default": 1,
"description": "Result page to fetch.",
"minimum": 1,
"title": "Page",
"type": "integer"
}
},
"required": [
"tag"
],
"title": "TagTopTracksParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"DataWindow": {
"properties": {
"page": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Page"
},
"per_page": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Per Page"
},
"total_pages": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Total Pages"
},
"total": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Total"
}
},
"title": "DataWindow",
"type": "object"
},
"TagTopTrackEntry": {
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"artist": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Artist"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Url"
},
"mbid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "MusicBrainz Identifier. May be null when Last.fm does not provide a MusicBrainz match.",
"title": "Mbid"
}
},
"required": [
"name"
],
"title": "TagTopTrackEntry",
"type": "object"
}
},
"properties": {
"success": {
"title": "Success",
"type": "boolean"
},
"tracks": {
"items": {
"$ref": "#/$defs/TagTopTrackEntry"
},
"title": "Tracks",
"type": "array"
},
"data_window": {
"anyOf": [
{
"$ref": "#/$defs/DataWindow"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"success",
"tracks"
],
"title": "TagTopTracksResult",
"type": "object"
}