# ListenBrainz

> Read anyone's public listening history on ListenBrainz, MetaBrainz's open alternative to Last.fm: their listens and what is playing now, top artists, albums and tracks for any period, listening activity, loved tracks, similar listeners and followers, playlists (including the ones ListenBrainz generates), site-wide charts, new releases from the artists they play, and track and artist details from MusicBrainz. A trigger runs a workflow for every new listen. No account or API key required.

App · 20 actions. Web page: https://docs.lodol.com/docs/integrations/listenbrainz

## Actions

### Find similar listeners

Find the listeners whose taste is closest to a user's, with how similar each is, most similar first. No API key required.

**Inputs**

- Username (`username`, text, required): The ListenBrainz username, as in the profile address listenbrainz.org/user/<name>. Pasting the profile link works too.

**Outputs**

- `count` (number): How many similar listeners came back.
- `username` (text): The ListenBrainz username these results are for.
- `users` (list): Listeners with the most similar taste first.

**Example output**

```json
{
  "count": 1,
  "username": "rob",
  "users": [
    {
      "profile_url": "https://listenbrainz.org/user/Violet%26Red/",
      "similarity": 0.5212,
      "similarity_percent": 52,
      "username": "Violet&Red"
    }
  ]
}
```

### Get artist countries

Get the countries the artists a user played come from: how many artists and listens each country accounts for, and its most played artists. No API key required.

**Inputs**

- Username (`username`, text, required): The ListenBrainz username, as in the profile address listenbrainz.org/user/<name>. Pasting the profile link works too.
- Time range (`time_range`, text): Which period to count. All time by default. 'Last' ranges are the previous full week, month, quarter, six months or year; ListenBrainz recalculates statistics about once a day. One of: `all_time` (All time), `this_week` (This week so far), `this_month` (This month so far), `this_year` (This year so far), `week` (Last week), `month` (Last month), `quarter` (Last quarter), `half_yearly` (Last six months), `year` (Last year). Default: `all_time`.

**Outputs**

- `countries` (list): Countries the played artists come from, most artists first.
- `last_updated` (text): When ListenBrainz last recalculated these statistics.
- `period_end` (text): The end of the period counted.
- `period_start` (text): The start of the period counted, as an ISO 8601 UTC time.
- `range` (text): The time range asked for, such as all_time or week.
- `range_label` (text): That range in words, such as 'Last week'.
- `stats_ready` (true/false): False when ListenBrainz has no statistics for this range yet, usually because there were no listens in it. The list is then empty.
- `total_countries` (number): How many countries are listed.
- `username` (text): The ListenBrainz username these results are for.

**Example output**

```json
{
  "countries": [
    {
      "artist_count": 282,
      "country_code": "GBR",
      "listen_count": 68541,
      "top_artists": [
        {
          "artist_mbid": "a8b39181-6939-451e-9641-2db231b73706",
          "artist_name": "Abakus",
          "listen_count": 3809
        },
        {
          "artist_mbid": "9a709693-b4f8-4da9-8cc1-038c911a61be",
          "artist_name": "Bonobo",
          "listen_count": 3536
        }
      ]
    }
  ],
  "last_updated": "2026-09-27T09:51:03Z",
  "period_end": "2026-09-27T00:00:00Z",
  "period_start": "2002-01-01T00:00:00Z",
  "range": "all_time",
  "range_label": "All time",
  "stats_ready": true,
  "total_countries": 1,
  "username": "rob"
}
```

### Get artist details

Get an artist's details from MusicBrainz by their ID: whether a person or group, where they are from, when they started, their tags and genres, and links to their website, socials and streaming pages. No API key required.

**Inputs**

- Artist ID (`artist_mbid`, text, required): The artist's MusicBrainz ID, as top artists or a listen returns it. A MusicBrainz or ListenBrainz artist link works too.

**Outputs**

- `area` (text): Where the artist is from.
- `artist_mbid` (text): The artist's MusicBrainz ID.
- `begin_year` (number): The year the artist was born or formed.
- `links` (list): The artist's websites, social profiles and streaming pages.
- `listenbrainz_url` (text): The artist's page on ListenBrainz.
- `musicbrainz_url` (text): The page for this on MusicBrainz.
- `name` (text): The artist's name.
- `tags` (list): Tags on the artist, most voted first.
- `type` (text): Person, Group, Orchestra and so on.

**Example output**

```json
{
  "area": "United Kingdom",
  "artist_mbid": "8f6bd1e4-fbe1-4f50-aa9b-94c450ec0f11",
  "begin_year": 1991,
  "links": [
    {
      "type": "official homepage",
      "url": "http://www.portishead.co.uk/"
    },
    {
      "type": "wikidata",
      "url": "https://www.wikidata.org/wiki/Q191352"
    }
  ],
  "listenbrainz_url": "https://listenbrainz.org/artist/8f6bd1e4-fbe1-4f50-aa9b-94c450ec0f11/",
  "musicbrainz_url": "https://musicbrainz.org/artist/8f6bd1e4-fbe1-4f50-aa9b-94c450ec0f11",
  "name": "Portishead",
  "tags": [
    {
      "is_genre": true,
      "tag": "trip hop",
      "votes": 16
    },
    {
      "is_genre": false,
      "tag": "bristol sound",
      "votes": 1
    }
  ],
  "type": "Group"
}
```

### Get followers and following

Get who follows a user on ListenBrainz and who they follow, as two lists of usernames. No API key required.

**Inputs**

- Username (`username`, text, required): The ListenBrainz username, as in the profile address listenbrainz.org/user/<name>. Pasting the profile link works too.

**Outputs**

- `follower_count` (number): How many people follow the user.
- `followers` (list): The usernames of the people who follow the user.
- `following` (list): The usernames of the people the user follows.
- `following_count` (number): How many people the user follows.
- `username` (text): The ListenBrainz username these results are for.

**Example output**

```json
{
  "follower_count": 2,
  "followers": [
    "ishaanshah",
    "aerozol"
  ],
  "following": [
    "Zas",
    "mr_monkey"
  ],
  "following_count": 2,
  "username": "rob"
}
```

### Get listen count

Get how many listens a user has recorded on ListenBrainz in all. No API key required.

**Inputs**

- Username (`username`, text, required): The ListenBrainz username, as in the profile address listenbrainz.org/user/<name>. Pasting the profile link works too.

**Outputs**

- `listen_count` (number): How many listens the user has recorded in all.
- `profile_url` (text): The user's ListenBrainz profile page.
- `username` (text): The ListenBrainz username these results are for.

**Example output**

```json
{
  "listen_count": 220287,
  "profile_url": "https://listenbrainz.org/user/rob/",
  "username": "rob"
}
```

### Get listening activity

Get how many listens a user recorded in each day, month or year of a time range, with the total. A range also covers the period before it, for comparing: last week lists 14 days. No API key required.

**Inputs**

- Username (`username`, text, required): The ListenBrainz username, as in the profile address listenbrainz.org/user/<name>. Pasting the profile link works too.
- Time range (`time_range`, text): Which period to count. All time by default. 'Last' ranges are the previous full week, month, quarter, six months or year; ListenBrainz recalculates statistics about once a day. One of: `all_time` (All time), `this_week` (This week so far), `this_month` (This month so far), `this_year` (This year so far), `week` (Last week), `month` (Last month), `quarter` (Last quarter), `half_yearly` (Last six months), `year` (Last year). Default: `all_time`.

**Outputs**

- `count` (number): How many periods are listed.
- `last_updated` (text): When ListenBrainz last recalculated these statistics.
- `period_end` (text): The end of the period counted.
- `period_start` (text): The start of the period counted, as an ISO 8601 UTC time.
- `periods` (list): One row per day, month or year, oldest first. A range covers both the current and the previous period, so 'Last week' lists 14 days.
- `range` (text): The time range asked for, such as all_time or week.
- `range_label` (text): That range in words, such as 'Last week'.
- `stats_ready` (true/false): False when ListenBrainz has no statistics for this range yet, usually because there were no listens in it. The list is then empty.
- `total_listens` (number): All the listens in the periods listed.
- `username` (text): The ListenBrainz username these results are for.

**Example output**

```json
{
  "count": 2,
  "last_updated": "2026-09-27T09:51:03Z",
  "period_end": "2026-01-01T00:00:00Z",
  "period_start": "2024-01-01T00:00:00Z",
  "periods": [
    {
      "end": "2024-01-31T23:59:59Z",
      "label": "January 2024",
      "listen_count": 2795,
      "start": "2024-01-01T00:00:00Z"
    },
    {
      "end": "2024-02-29T23:59:59Z",
      "label": "February 2024",
      "listen_count": 2087,
      "start": "2024-02-01T00:00:00Z"
    }
  ],
  "range": "year",
  "range_label": "Last year",
  "stats_ready": true,
  "total_listens": 4882,
  "username": "rob"
}
```

### Get listening by hour

Get how many listens a user recorded in each hour of each weekday (in UTC) over a time range, with totals per weekday and their busiest day and hour. No API key required.

**Inputs**

- Username (`username`, text, required): The ListenBrainz username, as in the profile address listenbrainz.org/user/<name>. Pasting the profile link works too.
- Time range (`time_range`, text): Which period to count. All time by default. 'Last' ranges are the previous full week, month, quarter, six months or year; ListenBrainz recalculates statistics about once a day. One of: `all_time` (All time), `this_week` (This week so far), `this_month` (This month so far), `this_year` (This year so far), `week` (Last week), `month` (Last month), `quarter` (Last quarter), `half_yearly` (Last six months), `year` (Last year). Default: `all_time`.

**Outputs**

- `busiest_day` (text): The weekday with the most listens.
- `busiest_hour_utc` (number): The hour of the day (0 to 23, UTC) with the most listens.
- `days` (list): Listens per weekday, Monday first.
- `hours` (list): Listens in each hour of each weekday (168 rows, Monday 0:00 first). Hours are UTC.
- `last_updated` (text): When ListenBrainz last recalculated these statistics.
- `period_end` (text): The end of the period counted.
- `period_start` (text): The start of the period counted, as an ISO 8601 UTC time.
- `range` (text): The time range asked for, such as all_time or week.
- `range_label` (text): That range in words, such as 'Last week'.
- `stats_ready` (true/false): False when ListenBrainz has no statistics for this range yet, usually because there were no listens in it. The list is then empty.
- `total_listens` (number): All the listens counted.
- `username` (text): The ListenBrainz username these results are for.

**Example output**

```json
{
  "busiest_day": "Monday",
  "busiest_hour_utc": 14,
  "days": [
    {
      "day": "Monday",
      "listen_count": 3245
    },
    {
      "day": "Tuesday",
      "listen_count": 0
    }
  ],
  "hours": [
    {
      "day": "Monday",
      "hour_utc": 13,
      "listen_count": 1671
    },
    {
      "day": "Monday",
      "hour_utc": 14,
      "listen_count": 1574
    }
  ],
  "last_updated": "2026-09-27T09:51:03Z",
  "period_end": "2026-09-27T00:00:00Z",
  "period_start": "2002-01-01T00:00:00Z",
  "range": "all_time",
  "range_label": "All time",
  "stats_ready": true,
  "total_listens": 3245,
  "username": "rob"
}
```

### Get listens

Get the tracks a user listened to, newest first: when, the track, artist and album, the player and service, cover art and the MusicBrainz IDs. Give a window of time to read a particular day or week. No API key required.

**Inputs**

- Username (`username`, text, required): The ListenBrainz username, as in the profile address listenbrainz.org/user/<name>. Pasting the profile link works too.
- Listened after (`listened_after`, date and time): Only listens after this moment. When it is set, the listens that came right after it are returned, up to How many, so raise that to reach further forward.
- Listened before (`listened_before`, date and time): Only listens before this moment. Leave both empty for the most recent listens.
- How many (`count`, number): How many to return, from 1 to 1,000. 25 by default. From 1 to 1000. Default: `25`.

**Outputs**

- `count` (number): How many listens came back.
- `first_listen_at` (text): When the user's earliest recorded listen was.
- `latest_listen_at` (text): When the user's most recent listen of all was, as an ISO 8601 UTC time.
- `listens` (list): The listens, newest first.
- `username` (text): The ListenBrainz username these results are for.

**Example output**

```json
{
  "count": 1,
  "first_listen_at": "2006-10-11T20:36:59Z",
  "latest_listen_at": "2026-02-18T11:28:29Z",
  "listens": [
    {
      "album_mbid": "1d98b0bc-5832-49d2-a93e-463032631a2f",
      "album_name": "Profound Mysteries II",
      "artist_mbids": [
        "1c70a3fc-fa3c-4be1-8b55-c3192db8a884"
      ],
      "artist_name": "R\u00f6yksopp",
      "cover_art_url": "https://coverartarchive.org/release/f1418001-7f1e-46af-bfdb-95faeded8841/32916450708-500.jpg",
      "duration_seconds": 402,
      "listened_at": "2026-02-18T11:28:29Z",
      "listened_at_unix": 1771414109,
      "music_service": null,
      "recording_mbid": "30d08f4c-d825-4ae1-b79c-44242cddd7c0",
      "recording_msid": "fd0cad33-ea33-453b-8155-1292379277db",
      "release_mbid": "e96c2e7b-94fd-4fbe-9c44-1a27d8664825",
      "submitted_with": "navidrome",
      "track_name": "Some Resolve",
      "track_url": null
    }
  ],
  "username": "rob"
}
```

### Get loved and hated tracks

Get the tracks a user marked as loved, or as hated, most recently marked first, with artist, album and cover art. No API key required.

**Inputs**

- Username (`username`, text, required): The ListenBrainz username, as in the profile address listenbrainz.org/user/<name>. Pasting the profile link works too.
- Which tracks (`feedback`, text): Loved tracks by default. One of: `loved` (Loved tracks), `hated` (Hated tracks), `both`. Default: `loved`.
- How many (`count`, number): How many to return, from 1 to 1,000. 25 by default. From 1 to 1000. Default: `25`.
- Skip (`offset`, number): How many to skip from the start of the list, to read further down it. 0 by default. From 0 to 100000. Default: `0`.

**Outputs**

- `count` (number): How many came back.
- `feedback` (text): Which tracks were asked for: loved, hated or both.
- `offset` (number): How many were skipped from the newest.
- `total` (number): How many tracks the user has marked that way in all.
- `tracks` (list): The tracks, most recently marked first.
- `username` (text): The ListenBrainz username these results are for.

**Example output**

```json
{
  "count": 1,
  "feedback": "loved",
  "offset": 0,
  "total": 94,
  "tracks": [
    {
      "album_name": "Solsbury Hill",
      "artist_mbids": [
        "2f548675-008d-4332-876c-108b0c7ab9c5"
      ],
      "artist_name": "Sia",
      "cover_art_url": "https://coverartarchive.org/release/4a9a1827-5423-49be-8370-1e1c529fab34/41190842555-500.jpg",
      "feedback": "loved",
      "given_at": "2025-03-14T17:12:08Z",
      "musicbrainz_url": "https://musicbrainz.org/recording/3b056314-4044-48dc-a28a-a81f307f2013",
      "recording_mbid": "3b056314-4044-48dc-a28a-a81f307f2013",
      "release_mbid": "4a9a1827-5423-49be-8370-1e1c529fab34",
      "track_name": "Solsbury Hill"
    }
  ],
  "username": "rob"
}
```

### Get new releases

Get albums, EPs and singles released recently or coming soon, either across MusicBrainz or only from the artists a user listens to. Each comes with its date, type, cover art and tags. No API key required.

**Inputs**

- Username (`username`, text): Only releases by artists this ListenBrainz user listens to. Leave empty for every new release.
- Days (`days`, number): How many days back (and ahead, for upcoming releases) to look, from 1 to 90. 14 by default. From 1 to 90. Default: `14`.
- Include released (`include_past`, true/false): Include releases already out. On by default. Default: `true`.
- Include upcoming (`include_upcoming`, true/false): Include releases not out yet. On by default. Default: `true`.
- Release types (`release_types`, list): Only these kinds of release. Leave empty for all. One or more of: `Album` (Albums), `EP` (EPs), `Single` (Singles), `Broadcast` (Broadcasts), `Other` (Other releases).
- Order (`sort`, text): Newest release date first by default. 'Artists the user plays most first' needs a username. One of: `newest` (Newest release date first), `oldest` (Oldest release date first), `artist` (Artist name, A to Z), `relevance` (Artists the user plays most first). Default: `newest`.
- How many (`limit`, number): The most releases to return, from 1 to 1,000. 100 by default. From 1 to 1000. Default: `100`.

**Outputs**

- `count` (number): How many came back.
- `days` (number): How many days either side of today were covered.
- `more_available` (true/false): True when raising the limit would return more.
- `releases` (list): The releases.
- `sort` (text): The order the releases are in.
- `total_matching` (number): How many releases matched in all.
- `username` (text): The user whose artists were followed. Empty for site-wide releases.

**Example output**

```json
{
  "count": 1,
  "days": 30,
  "more_available": true,
  "releases": [
    {
      "album_mbid": "efb25509-dad3-4a3b-a9f1-e81ede4067e3",
      "artist_mbids": [
        "1c70a3fc-fa3c-4be1-8b55-c3192db8a884",
        "d735497b-25f9-4503-8fb5-f50150730c18"
      ],
      "artist_name": "Ane Brun & R\u00f6yksopp",
      "cover_art_url": "https://coverartarchive.org/release/4da8c519-aec3-4f66-9dea-9b8cc95c6dac/46414277352-500.jpg",
      "musicbrainz_url": "https://musicbrainz.org/release/4da8c519-aec3-4f66-9dea-9b8cc95c6dac",
      "release_date": "2026-10-09",
      "release_mbid": "4da8c519-aec3-4f66-9dea-9b8cc95c6dac",
      "release_name": "Eat the Fruit",
      "relevance": 4258,
      "secondary_type": null,
      "tags": [
        "ambient pop",
        "art pop",
        "synth-pop"
      ],
      "type": "Single"
    }
  ],
  "sort": "newest",
  "total_matching": 133,
  "username": "rob"
}
```

### Get playlist

Get a public playlist with every track on it: title, artist, album, length, cover art and MusicBrainz ID. No API key required.

**Inputs**

- Playlist (`playlist`, text, required): The playlist's ID or its ListenBrainz link, from a playlist list or search.

**Outputs**

- `algorithm` (text): For a generated playlist, which kind it is, such as daily-jams or weekly-exploration. Empty for one a person made.
- `collaborators` (list): Other users who can edit it.
- `created_at` (text): When it was made, as an ISO 8601 UTC time.
- `created_for` (text): Who a generated playlist was made for.
- `creator` (text): Who made it: a username, or troi-bot and listenbrainz for playlists ListenBrainz generated.
- `description` (text): Its description as plain text.
- `last_modified_at` (text): When it was last changed.
- `playlist_mbid` (text): The playlist's ID. Pass it to 'Get playlist'.
- `public` (true/false): Whether anyone can see it.
- `title` (text): The playlist's title.
- `track_count` (number): How many tracks it holds.
- `tracks` (list): Every track, in playlist order.
- `url` (text): The playlist's page on ListenBrainz.

**Example output**

```json
{
  "algorithm": "weekly-jams",
  "collaborators": [],
  "created_at": "2026-08-23T22:07:21Z",
  "created_for": "rob",
  "creator": "listenbrainz",
  "description": "The ListenBrainz Weekly Jams playlist features songs that you have listened to before, arranged into a comfortable playlist.",
  "last_modified_at": "2026-08-23T22:07:21Z",
  "playlist_mbid": "54cc305b-f68e-4ab8-a2b9-3188727a3b5b",
  "public": true,
  "title": "Weekly Jams for rob, week of 2026-08-24 Mon",
  "track_count": 1,
  "tracks": [
    {
      "added_at": "2026-08-23T22:07:21Z",
      "added_by": "listenbrainz",
      "album_name": "Tomorrow\u2019s Harvest",
      "artist_mbids": [
        "69158f97-4c07-4c4e-baf8-4e4ab1ed666e"
      ],
      "artist_name": "Boards of Canada",
      "cover_art_url": "https://coverartarchive.org/release/d1f52538-291c-45a3-80a1-ac601f84ab87/4293243591-500.jpg",
      "duration_seconds": 222,
      "musicbrainz_url": "https://musicbrainz.org/recording/28b58f86-dc23-4745-ba8d-1964f2c1c23a",
      "position": 1,
      "recording_mbid": "28b58f86-dc23-4745-ba8d-1964f2c1c23a",
      "title": "Cold Earth"
    }
  ],
  "url": "https://listenbrainz.org/playlist/54cc305b-f68e-4ab8-a2b9-3188727a3b5b/"
}
```

### Get site-wide charts

Get the most played artists, albums or tracks across all of ListenBrainz in a time range, with play counts and cover art. No API key required.

**Inputs**

- Chart (`chart`, text): What to rank. Artists by default. One of: `artists`, `albums`, `tracks`. Default: `artists`.
- Time range (`time_range`, text): Which period to count. All time by default. 'Last' ranges are the previous full week, month, quarter, six months or year; ListenBrainz recalculates statistics about once a day. One of: `all_time` (All time), `this_week` (This week so far), `this_month` (This month so far), `this_year` (This year so far), `week` (Last week), `month` (Last month), `quarter` (Last quarter), `half_yearly` (Last six months), `year` (Last year). Default: `all_time`.
- How many (`count`, number): How many to return, from 1 to 1,000. 25 by default. From 1 to 1000. Default: `25`.
- Skip (`offset`, number): How many to skip from the start of the list, to read further down it. 0 by default. From 0 to 100000. Default: `0`.

**Outputs**

- `chart` (text): What is ranked: artists, albums or tracks.
- `count` (number): How many came back.
- `entries` (list): Most played first.
- `last_updated` (text): When ListenBrainz last recalculated these statistics.
- `offset` (number): How many places were skipped from the top.
- `period_end` (text): The end of the period counted.
- `period_start` (text): The start of the period counted, as an ISO 8601 UTC time.
- `range` (text): The time range asked for, such as all_time or week.
- `range_label` (text): That range in words, such as 'Last week'.
- `stats_ready` (true/false): False when ListenBrainz has no statistics for this range yet, usually because there were no listens in it. The list is then empty.
- `total_entries` (number): How many different entries were played in the range.

**Example output**

```json
{
  "chart": "tracks",
  "count": 1,
  "entries": [
    {
      "album_name": "ARIRANG",
      "artist_mbids": [
        "0d79fe8e-ba27-4859-bb8c-2f255f346853"
      ],
      "artist_name": "BTS",
      "cover_art_url": "https://coverartarchive.org/release/20af35dd-dda2-47de-8ea5-78211c0dfe9c/44649396012-500.jpg",
      "listen_count": 181789,
      "mbid": "6f33dc05-cdc0-4a2f-8039-e8fed082eec6",
      "musicbrainz_url": "https://musicbrainz.org/recording/6f33dc05-cdc0-4a2f-8039-e8fed082eec6",
      "name": "SWIM",
      "rank": 1
    }
  ],
  "last_updated": "2026-10-19T22:58:38Z",
  "offset": 0,
  "period_end": "2026-10-19T00:00:00Z",
  "period_start": "2026-10-12T00:00:00Z",
  "range": "week",
  "range_label": "Last week",
  "stats_ready": true,
  "total_entries": 2928100
}
```

### Get top albums

Get the albums a user played most in a time range, with their artist, cover art and play count, most played first. No API key required.

**Inputs**

- Username (`username`, text, required): The ListenBrainz username, as in the profile address listenbrainz.org/user/<name>. Pasting the profile link works too.
- Time range (`time_range`, text): Which period to count. All time by default. 'Last' ranges are the previous full week, month, quarter, six months or year; ListenBrainz recalculates statistics about once a day. One of: `all_time` (All time), `this_week` (This week so far), `this_month` (This month so far), `this_year` (This year so far), `week` (Last week), `month` (Last month), `quarter` (Last quarter), `half_yearly` (Last six months), `year` (Last year). Default: `all_time`.
- How many (`count`, number): How many to return, from 1 to 1,000. 25 by default. From 1 to 1000. Default: `25`.
- Skip (`offset`, number): How many to skip from the start of the list, to read further down it. 0 by default. From 0 to 100000. Default: `0`.

**Outputs**

- `albums` (list): Most played first.
- `count` (number): How many came back.
- `last_updated` (text): When ListenBrainz last recalculated these statistics.
- `offset` (number): How many places were skipped from the top.
- `period_end` (text): The end of the period counted.
- `period_start` (text): The start of the period counted, as an ISO 8601 UTC time.
- `range` (text): The time range asked for, such as all_time or week.
- `range_label` (text): That range in words, such as 'Last week'.
- `stats_ready` (true/false): False when ListenBrainz has no statistics for this range yet, usually because there were no listens in it. The list is then empty.
- `total_albums` (number): How many different albums were played in the range.
- `username` (text): The ListenBrainz username these results are for.

**Example output**

```json
{
  "albums": [
    {
      "album_mbid": "9470253b-7102-398b-bda0-f010e92c9955",
      "album_name": "Filling Up the City Skies",
      "artist_mbids": [
        "3a07764c-7cc5-42e9-8205-3de7532f4771"
      ],
      "artist_name": "Pretty Lights",
      "cover_art_url": "https://coverartarchive.org/release/dda07cd4-efaa-400a-8151-08c29729604a/23255889740-500.jpg",
      "listen_count": 1699,
      "listenbrainz_url": "https://listenbrainz.org/album/9470253b-7102-398b-bda0-f010e92c9955/",
      "rank": 1,
      "release_mbid": "dda07cd4-efaa-400a-8151-08c29729604a"
    }
  ],
  "count": 1,
  "last_updated": "2026-09-27T09:51:03Z",
  "offset": 0,
  "period_end": "2026-09-27T00:00:00Z",
  "period_start": "2002-01-01T00:00:00Z",
  "range": "all_time",
  "range_label": "All time",
  "stats_ready": true,
  "total_albums": 12595,
  "username": "rob"
}
```

### Get top artists

Get the artists a user played most in a time range, with how many times each, most played first. An empty list with 'Stats ready' false means no listens were counted in that range. No API key required.

**Inputs**

- Username (`username`, text, required): The ListenBrainz username, as in the profile address listenbrainz.org/user/<name>. Pasting the profile link works too.
- Time range (`time_range`, text): Which period to count. All time by default. 'Last' ranges are the previous full week, month, quarter, six months or year; ListenBrainz recalculates statistics about once a day. One of: `all_time` (All time), `this_week` (This week so far), `this_month` (This month so far), `this_year` (This year so far), `week` (Last week), `month` (Last month), `quarter` (Last quarter), `half_yearly` (Last six months), `year` (Last year). Default: `all_time`.
- How many (`count`, number): How many to return, from 1 to 1,000. 25 by default. From 1 to 1000. Default: `25`.
- Skip (`offset`, number): How many to skip from the start of the list, to read further down it. 0 by default. From 0 to 100000. Default: `0`.

**Outputs**

- `artists` (list): Most played first.
- `count` (number): How many came back.
- `last_updated` (text): When ListenBrainz last recalculated these statistics.
- `offset` (number): How many places were skipped from the top.
- `period_end` (text): The end of the period counted.
- `period_start` (text): The start of the period counted, as an ISO 8601 UTC time.
- `range` (text): The time range asked for, such as all_time or week.
- `range_label` (text): That range in words, such as 'Last week'.
- `stats_ready` (true/false): False when ListenBrainz has no statistics for this range yet, usually because there were no listens in it. The list is then empty.
- `total_artists` (number): How many different artists were played in the range.
- `username` (text): The ListenBrainz username these results are for.

**Example output**

```json
{
  "artists": [
    {
      "artist_mbid": "c24b47a1-2f52-44f3-a3c6-374dca844731",
      "artist_name": "Wax Tailor",
      "listen_count": 4298,
      "listenbrainz_url": "https://listenbrainz.org/artist/c24b47a1-2f52-44f3-a3c6-374dca844731/",
      "rank": 1
    },
    {
      "artist_mbid": "1c70a3fc-fa3c-4be1-8b55-c3192db8a884",
      "artist_name": "R\u00f6yksopp",
      "listen_count": 4249,
      "listenbrainz_url": "https://listenbrainz.org/artist/1c70a3fc-fa3c-4be1-8b55-c3192db8a884/",
      "rank": 2
    }
  ],
  "count": 2,
  "last_updated": "2026-09-27T09:51:03Z",
  "offset": 0,
  "period_end": "2026-09-27T00:00:00Z",
  "period_start": "2002-01-01T00:00:00Z",
  "range": "all_time",
  "range_label": "All time",
  "stats_ready": true,
  "total_artists": 8629,
  "username": "rob"
}
```

### Get top tracks

Get the tracks a user played most in a time range, with their artist, album, cover art and play count, most played first. No API key required.

**Inputs**

- Username (`username`, text, required): The ListenBrainz username, as in the profile address listenbrainz.org/user/<name>. Pasting the profile link works too.
- Time range (`time_range`, text): Which period to count. All time by default. 'Last' ranges are the previous full week, month, quarter, six months or year; ListenBrainz recalculates statistics about once a day. One of: `all_time` (All time), `this_week` (This week so far), `this_month` (This month so far), `this_year` (This year so far), `week` (Last week), `month` (Last month), `quarter` (Last quarter), `half_yearly` (Last six months), `year` (Last year). Default: `all_time`.
- How many (`count`, number): How many to return, from 1 to 1,000. 25 by default. From 1 to 1000. Default: `25`.
- Skip (`offset`, number): How many to skip from the start of the list, to read further down it. 0 by default. From 0 to 100000. Default: `0`.

**Outputs**

- `count` (number): How many came back.
- `last_updated` (text): When ListenBrainz last recalculated these statistics.
- `offset` (number): How many places were skipped from the top.
- `period_end` (text): The end of the period counted.
- `period_start` (text): The start of the period counted, as an ISO 8601 UTC time.
- `range` (text): The time range asked for, such as all_time or week.
- `range_label` (text): That range in words, such as 'Last week'.
- `stats_ready` (true/false): False when ListenBrainz has no statistics for this range yet, usually because there were no listens in it. The list is then empty.
- `total_tracks` (number): How many different tracks were played in the range.
- `tracks` (list): Most played first.
- `username` (text): The ListenBrainz username these results are for.

**Example output**

```json
{
  "count": 1,
  "last_updated": "2026-09-27T09:51:03Z",
  "offset": 0,
  "period_end": "2026-09-27T00:00:00Z",
  "period_start": "2002-01-01T00:00:00Z",
  "range": "all_time",
  "range_label": "All time",
  "stats_ready": true,
  "total_tracks": 33900,
  "tracks": [
    {
      "album_name": "Maps From the Wilderness",
      "artist_mbids": [
        "3fa17b15-b8d1-46c4-a0e3-6e0f2a064a1d"
      ],
      "artist_name": "TM Juke",
      "cover_art_url": "https://coverartarchive.org/release/d3654b5e-160f-4a96-bacf-aea5242a2df0/3246868285-500.jpg",
      "listen_count": 243,
      "musicbrainz_url": "https://musicbrainz.org/recording/586a6fc2-804e-4e60-a115-217d8ae9e90d",
      "rank": 1,
      "recording_mbid": "586a6fc2-804e-4e60-a115-217d8ae9e90d",
      "release_mbid": "d3654b5e-160f-4a96-bacf-aea5242a2df0",
      "track_name": "Just for a Day (Sunday)"
    }
  ],
  "username": "rob"
}
```

### Get track details

Get a track's details from MusicBrainz by its ID: artists, length, first release date, album and year, ISRC codes, tags and genres, performer credits and streaming links. No API key required.

**Inputs**

- Track ID (`recording_mbid`, text, required): The track's MusicBrainz recording ID, as a listen, top tracks list or playlist returns it. A MusicBrainz link works too.

**Outputs**

- `album_artist_name` (text): That album's artist.
- `album_mbid` (text): The MusicBrainz release group ID: the album across all its editions.
- `album_name` (text): The album (release) ListenBrainz links the track to.
- `album_tags` (list): Tags on its album.
- `artist_name` (text): The artist as credited.
- `artist_tags` (list): Tags on its artists.
- `artists` (list): Each credited artist.
- `cover_art_url` (text): A 500 pixel cover image from the Cover Art Archive. Empty when there is none.
- `credits` (list): Performers and their roles.
- `first_release_date` (text): When the track was first released, YYYY-MM-DD.
- `isrcs` (list): The track's ISRC codes.
- `length_seconds` (number): How long the track is.
- `links` (list): Where to stream or buy the track.
- `musicbrainz_url` (text): The page for this on MusicBrainz.
- `recording_mbid` (text): The track's MusicBrainz recording ID.
- `release_mbid` (text): The MusicBrainz ID of the release (the edition of the album).
- `release_year` (number): The year that album came out.
- `tags` (list): Tags on the track, most voted first.
- `track_name` (text): The track's title.

**Example output**

```json
{
  "album_artist_name": "R\u00f6yksopp",
  "album_mbid": "1d98b0bc-5832-49d2-a93e-463032631a2f",
  "album_name": "Profound Mysteries II",
  "album_tags": [
    {
      "is_genre": true,
      "tag": "synth-pop",
      "votes": 1
    }
  ],
  "artist_name": "R\u00f6yksopp",
  "artist_tags": [
    {
      "is_genre": true,
      "tag": "electronic",
      "votes": 12
    }
  ],
  "artists": [
    {
      "area": "Norway",
      "artist_mbid": "1c70a3fc-fa3c-4be1-8b55-c3192db8a884",
      "begin_year": 1998,
      "join_phrase": "",
      "name": "R\u00f6yksopp",
      "type": "Group"
    }
  ],
  "cover_art_url": "https://coverartarchive.org/release/f1418001-7f1e-46af-bfdb-95faeded8841/32916450708-500.jpg",
  "credits": [
    {
      "artist_mbid": "8695150e-aa0f-4330-ae02-dccf51dd1fe1",
      "artist_name": "Kato \u00c5dland",
      "instrument": "bass guitar",
      "role": "instrument"
    }
  ],
  "first_release_date": "2022-08-19",
  "isrcs": [
    "GBW232100119"
  ],
  "length_seconds": 402,
  "links": [
    {
      "type": "streaming",
      "url": "https://tidal.com/track/243062918"
    }
  ],
  "musicbrainz_url": "https://musicbrainz.org/recording/30d08f4c-d825-4ae1-b79c-44242cddd7c0",
  "recording_mbid": "30d08f4c-d825-4ae1-b79c-44242cddd7c0",
  "release_mbid": "f1418001-7f1e-46af-bfdb-95faeded8841",
  "release_year": 2022,
  "tags": [
    {
      "is_genre": true,
      "tag": "electronic",
      "votes": 2
    }
  ],
  "track_name": "Some Resolve"
}
```

### Get what's playing now

See what a user's player says is playing right now, if anything: the track, artist, album and the service it is playing on. 'Is playing' is false when nothing is. No API key required.

**Inputs**

- Username (`username`, text, required): The ListenBrainz username, as in the profile address listenbrainz.org/user/<name>. Pasting the profile link works too.

**Outputs**

- `album_name` (text): Its album.
- `artist_mbids` (list): The MusicBrainz IDs of every credited artist. Pass one to 'Get artist details'.
- `artist_name` (text): Its artist.
- `cover_art_url` (text): A 500 pixel cover image from the Cover Art Archive. Empty when there is none.
- `duration_seconds` (number): How long the track is.
- `is_playing` (true/false): True when the user's player reports a track playing right now.
- `music_service` (text): Where it was played, such as Spotify, when known.
- `recording_mbid` (text): The track's MusicBrainz recording ID. Pass it to 'Get track details'. Empty when ListenBrainz could not match the track to MusicBrainz.
- `release_mbid` (text): The MusicBrainz ID of the release (the edition of the album).
- `submitted_with` (text): The app that sent the listen to ListenBrainz, such as Web Scrobbler.
- `summary` (text): One line saying what is playing, or that nothing is.
- `track_name` (text): The track playing. Empty when nothing is.
- `track_url` (text): A link to the track on the service it was played on.
- `username` (text): The ListenBrainz username these results are for.

**Example output**

```json
{
  "album_name": "ARIRANG",
  "artist_mbids": [],
  "artist_name": "BTS",
  "cover_art_url": null,
  "duration_seconds": 227,
  "is_playing": true,
  "music_service": "Spotify",
  "recording_mbid": null,
  "release_mbid": null,
  "submitted_with": "Web Scrobbler",
  "summary": "Ateeteeee is listening to Into the Sun by BTS",
  "track_name": "Into the Sun",
  "track_url": "https://open.spotify.com/track/1ZNolq7VI7efGlh2hb2VVr",
  "username": "Ateeteeee"
}
```

### List a user's playlists

List the public playlists a user made or saved, newest first, with their links. Use 'Get playlist' for the tracks. No API key required.

**Inputs**

- Username (`username`, text, required): The ListenBrainz username, as in the profile address listenbrainz.org/user/<name>. Pasting the profile link works too.
- How many (`count`, number): How many playlists to return, from 1 to 100. 25 by default. From 1 to 100. Default: `25`.
- Skip (`offset`, number): How many to skip from the start of the list, to read further down it. 0 by default. From 0 to 100000. Default: `0`.

**Outputs**

- `count` (number): How many came back.
- `offset` (number): How many were skipped from the newest.
- `playlists` (list): The playlists, newest first.
- `total` (number): How many playlists there are in all.
- `username` (text): The ListenBrainz username these results are for.

**Example output**

```json
{
  "count": 1,
  "offset": 0,
  "playlists": [
    {
      "algorithm": "weekly-jams",
      "collaborators": [],
      "created_at": "2026-08-23T22:07:21Z",
      "created_for": "rob",
      "creator": "listenbrainz",
      "description": "The ListenBrainz Weekly Jams playlist features songs that you have listened to before, arranged into a comfortable playlist.",
      "last_modified_at": "2026-08-23T22:07:21Z",
      "playlist_mbid": "54cc305b-f68e-4ab8-a2b9-3188727a3b5b",
      "public": true,
      "title": "Weekly Jams for rob, week of 2026-08-24 Mon",
      "url": "https://listenbrainz.org/playlist/54cc305b-f68e-4ab8-a2b9-3188727a3b5b/"
    }
  ],
  "total": 46,
  "username": "rob"
}
```

### List playlists made for a user

List the playlists ListenBrainz generated for a user, such as Daily Jams, Weekly Jams and Weekly Exploration, newest first. Older ones are replaced as new ones are made. No API key required.

**Inputs**

- Username (`username`, text, required): The ListenBrainz username, as in the profile address listenbrainz.org/user/<name>. Pasting the profile link works too.
- How many (`count`, number): How many playlists to return, from 1 to 100. 25 by default. From 1 to 100. Default: `25`.
- Skip (`offset`, number): How many to skip from the start of the list, to read further down it. 0 by default. From 0 to 100000. Default: `0`.

**Outputs**

- `count` (number): How many came back.
- `offset` (number): How many were skipped from the newest.
- `playlists` (list): The playlists, newest first.
- `total` (number): How many playlists there are in all.
- `username` (text): The ListenBrainz username these results are for.

**Example output**

```json
{
  "count": 1,
  "offset": 0,
  "playlists": [
    {
      "algorithm": "weekly-jams",
      "collaborators": [],
      "created_at": "2026-08-23T22:07:21Z",
      "created_for": "rob",
      "creator": "listenbrainz",
      "description": "The ListenBrainz Weekly Jams playlist features songs that you have listened to before, arranged into a comfortable playlist.",
      "last_modified_at": "2026-08-23T22:07:21Z",
      "playlist_mbid": "54cc305b-f68e-4ab8-a2b9-3188727a3b5b",
      "public": true,
      "title": "Weekly Jams for rob, week of 2026-08-24 Mon",
      "url": "https://listenbrainz.org/playlist/54cc305b-f68e-4ab8-a2b9-3188727a3b5b/"
    }
  ],
  "total": 46,
  "username": "rob"
}
```

### Search playlists

Find public playlists whose title or description resembles your words, closest match first. No API key required.

**Inputs**

- Search for (`query`, text, required): Words from a playlist's title or description, at least 3 characters.
- How many (`count`, number): How many playlists to return, from 1 to 100. 25 by default. From 1 to 100. Default: `25`.
- Skip (`offset`, number): How many to skip from the start of the list, to read further down it. 0 by default. From 0 to 100000. Default: `0`.

**Outputs**

- `count` (number): How many came back.
- `offset` (number): How many were skipped from the newest.
- `playlists` (list): The playlists, newest first.
- `query` (text): The words searched for.
- `total` (number): How many playlists there are in all.

**Example output**

```json
{
  "count": 1,
  "offset": 0,
  "playlists": [
    {
      "algorithm": null,
      "collaborators": [],
      "created_at": "2024-08-10T09:44:39Z",
      "created_for": null,
      "creator": "protodeniz",
      "description": null,
      "last_modified_at": "2024-08-10T09:44:39Z",
      "playlist_mbid": "510205aa-6480-4624-928c-43532d3baf80",
      "public": true,
      "title": "Jazz",
      "url": "https://listenbrainz.org/playlist/510205aa-6480-4624-928c-43532d3baf80/"
    }
  ],
  "query": "jazz",
  "total": 565
}
```
