Browser Skills

https://musicbrainz.org — open music encyclopedia with a fully free JSON API. No auth required for reads. No browser needed for any documented workflow.

Field-tested against musicbrainz.org on 2026-04-18.

Do this first

The MusicBrainz Web Service API (ws/2) returns clean JSON for all entity types — no browser needed.

python

from helpers import http_get
import json

# REQUIRED: every request must include this header or you get HTTP 403
UA = {"User-Agent": "browser-harness/1.0 (your@email.com)"}

data = json.loads(http_get("https://musicbrainz.org/ws/2/artist/?query=queen&fmt=json&limit=5", headers=UA))
for a in data['artists']:
    print(a['id'], a['name'], a.get('type'), a.get('country'), a['score'])
# 0383dadf-2a4e-4d10-a46a-e9e041da8eb3  Queen  Group  GB  100
# 79239441-bfd5-4981-a70c-55c3f15c1287  Madonna  Person  US  73

User-Agent is mandatory — omitting it returns HTTP 403 immediately. Format: AppName/Version (contact@email.com).

Entity types

Entity	Endpoint	Key fields
`artist`	`/ws/2/artist/`	name, sort-name, type (Group/Person/Orchestra/Choir), country, life-span, tags, rating
`release-group`	`/ws/2/release-group/`	title, primary-type (Album/Single/EP/Other), first-release-date
`release`	`/ws/2/release/`	title, date, country, status (Official/Bootleg/Promotional), barcode, label-info, media
`recording`	`/ws/2/recording/`	title, length (milliseconds), artist-credit, releases
`label`	`/ws/2/label/`	name, type, country, area
`work`	`/ws/2/work/`	title, type (Song/Aria/Soundtrack/etc.), relations

All entities share the same MBID (MusicBrainz ID) format: UUID v4, e.g. 0383dadf-2a4e-4d10-a46a-e9e041da8eb3.

Common workflows

Artist search

python

from helpers import http_get
import json

UA = {"User-Agent": "browser-harness/1.0 (your@email.com)"}

resp = json.loads(http_get(
    "https://musicbrainz.org/ws/2/artist/?query=queen&fmt=json&limit=5",
    headers=UA
))
# resp keys: count (total matches), offset, artists (list)
for a in resp['artists']:
    print(a['id'])           # MBID: 0383dadf-2a4e-4d10-a46a-e9e041da8eb3
    print(a['name'])         # Queen
    print(a['sort-name'])    # Queen  (differs for persons: "Bowie, David")
    print(a.get('type'))     # Group / Person / Orchestra / Choir
    print(a.get('country'))  # GB
    print(a.get('life-span'))# {'begin': '1970-06-27', 'end': None, 'ended': True}
    print(a.get('disambiguation', ''))  # e.g. "English singer-songwriter"
    print(a['score'])        # relevance 0-100

Artist by MBID (with related data via `inc=`)

python

# inc= parameters stack with + between them
resp = json.loads(http_get(
    "https://musicbrainz.org/ws/2/artist/0383dadf-2a4e-4d10-a46a-e9e041da8eb3"
    "?inc=releases+tags+ratings+release-groups&fmt=json",
    headers=UA
))
print(resp['name'])      # Queen
print(resp['type'])      # Group
print(resp['country'])   # GB
print(resp['life-span']) # {'begin': '1970-06-27', 'end': None, 'ended': True}

# Tags (community-voted genre labels, sorted by count)
tags = sorted(resp.get('tags', []), key=lambda x: x['count'], reverse=True)
print([t['name'] for t in tags[:5]])
# ['rock', 'glam rock', 'hard rock', 'art rock', 'british']

# Rating (community score, 0-5)
print(resp.get('rating'))  # {'votes-count': 43, 'value': 4.7}

# Direct releases (up to 25 per request — use browse for full list)
for r in resp.get('releases', []):
    print(r['id'], r['title'], r.get('date'))

# Release groups (albums, singles, EPs — deduplicated by edition)
for rg in resp.get('release-groups', []):
    print(rg['id'], rg['title'], rg.get('primary-type'), rg.get('first-release-date'))
# 6b47c9a0  A Night at the Opera  Album  1975-11-21
# 002ed683  Sheer Heart Attack    Album  1974-11-01

Browse releases by artist (full list)

python

# Browse API: uses 'artist' param (not 'query') — response key is 'release-count' not 'count'
resp = json.loads(http_get(
    "https://musicbrainz.org/ws/2/release/"
    "?artist=0383dadf-2a4e-4d10-a46a-e9e041da8eb3&fmt=json&limit=25&offset=0",
    headers=UA
))
print(resp['release-count'])   # 1635 — total releases for this artist
for r in resp['releases']:
    print(r['id'], r['title'], r.get('date'), r.get('country'), r.get('status'))
    # Also has: cover-art-archive.artwork (bool), cover-art-archive.front (bool)
    caa = r.get('cover-art-archive', {})
    print(caa.get('artwork'), caa.get('front'), caa.get('count'))

# Paginate: increment offset by limit

Release search and lookup

python

# Search by title
resp = json.loads(http_get(
    "https://musicbrainz.org/ws/2/release/?query=dark+side+of+the+moon&fmt=json&limit=5",
    headers=UA
))
# resp keys: count, offset, releases

# Full release with track list, artists, and labels
release = json.loads(http_get(
    "https://musicbrainz.org/ws/2/release/b84ee12a-09ef-421b-82de-0441a926375b"
    "?inc=artists+recordings+labels+release-groups&fmt=json",
    headers=UA
))
print(release['title'])   # The Dark Side of the Moon
print(release['date'])    # 1973-03-24
print(release['status'])  # Official
print(release['country']) # GB

# Release group (the "album concept", deduplicates editions)
rg = release.get('release-group', {})
print(rg['title'], rg.get('primary-type'), rg['id'])
# The Dark Side of the Moon  Album  f5093c06-23e3-404f-aeaa-40f72885ee3a

# Artist credit
for ac in release.get('artist-credit', []):
    if isinstance(ac, dict) and 'artist' in ac:
        print(ac['artist']['name'], ac['artist']['id'])
        # Pink Floyd  83d91898-7763-47d7-b03b-b92132375c47

# Labels
for li in release.get('label-info', []):
    label = li.get('label', {})
    print(label.get('name'), li.get('catalog-number'))
    # Harvest  SHVL 804

# Track list (from media[].tracks[])
for disc in release.get('media', []):
    for track in disc.get('tracks', []):
        dur_s = track['length'] // 1000 if track.get('length') else None
        rec = track.get('recording', {})
        print(track['number'], track['title'], dur_s, rec.get('id'))
        # A1  Speak to Me  68s  bef3fddb-5aca-49f5-b2fd-d56a23268d63
        # A2  Breathe      168s ecbc7c9b-e79d-4ec8-ac77-44e4a7f7f1b8

Recording (track) search

python

# Use Lucene field syntax to filter by artist
resp = json.loads(http_get(
    "https://musicbrainz.org/ws/2/recording/"
    "?query=bohemian+rhapsody+AND+artist:queen&fmt=json&limit=5",
    headers=UA
))
print(resp['count'])  # 419
for r in resp['recordings']:
    dur_s = r['length'] // 1000 if r.get('length') else None
    artists = [ac['artist']['name'] for ac in r.get('artist-credit', []) if isinstance(ac, dict)]
    releases = r.get('releases', [])
    print(r['id'], r['title'], dur_s, artists, releases[0]['title'] if releases else None)
# a4803b45  Bohemian Rhapsody  130s  ['Queen']  Rhapsody in Red
# 40212eb6  Bohemian Rhapsody  338s  ['Queen']  1986-07: Wembley Stadium

Release-group search (deduplicated albums)

python

# Use release-group endpoint to avoid getting every regional edition
resp = json.loads(http_get(
    "https://musicbrainz.org/ws/2/release-group/"
    "?query=release-group:\"A+Night+at+the+Opera\"+AND+artist:queen&fmt=json&limit=5",
    headers=UA
))
# resp keys: count, release-groups
for rg in resp.get('release-groups', []):
    print(rg['id'], rg['title'], rg.get('primary-type'), rg.get('first-release-date'), rg['score'])
# 6b47c9a0  A Night at the Opera  Album  1975-11-21  100

# Browse release-groups for an artist
resp = json.loads(http_get(
    "https://musicbrainz.org/ws/2/release-group/"
    "?artist=0383dadf-2a4e-4d10-a46a-e9e041da8eb3&fmt=json&limit=25",
    headers=UA
))
print(resp['release-group-count'])  # 412
for rg in resp.get('release-groups', []):
    print(rg['title'], rg.get('primary-type'), rg.get('first-release-date'))

Label and work lookups

python

# Label search
resp = json.loads(http_get(
    "https://musicbrainz.org/ws/2/label/?query=EMI&fmt=json&limit=3",
    headers=UA
))
for l in resp['labels']:
    print(l['id'], l['name'], l.get('type'), l.get('country'), l['score'])
# c029628b  EMI  Original Production  GB  100

# Work (song composition — author-level, not performance-level)
resp = json.loads(http_get(
    "https://musicbrainz.org/ws/2/work/?query=bohemian+rhapsody&fmt=json&limit=3",
    headers=UA
))
for w in resp['works']:
    print(w['id'], w['title'], w.get('type'), w['score'])
# 41c94a08  Bohemian Rhapsody  Song  100

Cover Art Archive

python

# Get cover art for a release MBID
# 404 if no artwork has been uploaded for that release
def get_cover_art(release_mbid, size="500"):
    """
    size: '250', '500', '1200', or 'full' (original file)
    Returns the front cover URL, or None if no artwork exists.
    """
    try:
        resp = json.loads(http_get(
            f"https://coverartarchive.org/release/{release_mbid}",
            headers=UA
        ))
    except Exception:
        return None   # 404 = no art uploaded

    images = resp.get('images', [])
    # Prefer an image flagged as front=True
    front = next((img for img in images if img.get('front')), None)
    img = front or (images[0] if images else None)
    if not img:
        return None

    if size == 'full':
        return img['image']
    return img['thumbnails'].get(size) or img['thumbnails'].get('large')

# Thumbnail sizes confirmed: '250', '500', '1200', 'small' (=250), 'large' (=500)

url = get_cover_art("b84ee12a-09ef-421b-82de-0441a926375b")
# http://coverartarchive.org/release/b84ee12a.../1611507818-500.jpg

# Full images response structure
resp = json.loads(http_get(
    "https://coverartarchive.org/release/b84ee12a-09ef-421b-82de-0441a926375b",
    headers=UA
))
for img in resp['images']:
    print(img.get('types'))   # ['Front'], ['Back'], ['Liner'], ['Poster'], ['Medium'], ['Sticker'], ['Other']
    print(img.get('front'))   # True only for front=True flagged images (not all 'Front' types)
    print(img.get('approved'))# True/False
    print(img['image'])       # full resolution URL
    print(img['thumbnails'])  # {'small': '...-250.jpg', 'large': '...-500.jpg', '250': ..., '500': ..., '1200': ...}

Lucene query syntax for search

All search endpoints support Lucene field queries:

python

# Field search: artist:, type:, country:, tag:, release:, date:
resp = json.loads(http_get(
    "https://musicbrainz.org/ws/2/artist/"
    "?query=artist:queen+AND+type:group+AND+country:GB&fmt=json&limit=5",
    headers=UA
))
# count: 23 (exact matches only)

# Phrase search with quotes
resp = json.loads(http_get(
    "https://musicbrainz.org/ws/2/release/"
    '?query=release:"A+Night+at+the+Opera"+AND+artist:queen&fmt=json&limit=5',
    headers=UA
))

Common Lucene field names per entity:

artist: artist:, type:, country:, tag:, begin:, end:
release: release:, artist:, date:, country:, status:, label:, barcode:
recording: recording:, artist:, release:, dur: (milliseconds), tnum: (track number)
release-group: release-group:, artist:, primarytype:, secondarytype:

Parallel fetching

python

from concurrent.futures import ThreadPoolExecutor

UA = {"User-Agent": "browser-harness/1.0 (your@email.com)"}

def fetch_artist(mbid):
    resp = json.loads(http_get(
        f"https://musicbrainz.org/ws/2/artist/{mbid}?inc=tags&fmt=json",
        headers=UA
    ))
    tags = [t['name'] for t in sorted(resp.get('tags', []), key=lambda x: x['count'], reverse=True)[:3]]
    return {"name": resp['name'], "type": resp.get('type'), "tags": tags}

mbids = [
    "0383dadf-2a4e-4d10-a46a-e9e041da8eb3",  # Queen
    "83d91898-7763-47d7-b03b-b92132375c47",  # Pink Floyd
    "678d88b2-87b0-403b-b63d-5da7465aecc3",  # Led Zeppelin
]

with ThreadPoolExecutor(max_workers=3) as ex:
    results = list(ex.map(fetch_artist, mbids))
# 3 artists fetched in ~0.79s total

Tested: 5-6 rapid sequential requests all succeed. Parallel requests at 3x concurrency succeed. Real 429s (rate-limit blocks) are only hit at very high burst rates; if you do get a 429, add time.sleep(1) between requests.

Pagination

python

import time

UA = {"User-Agent": "browser-harness/1.0 (your@email.com)"}

def browse_all_releases(artist_mbid, page_size=25):
    """Fetch all releases for an artist across multiple pages."""
    offset = 0
    total = None
    releases = []
    while total is None or offset < total:
        resp = json.loads(http_get(
            f"https://musicbrainz.org/ws/2/release/"
            f"?artist={artist_mbid}&fmt=json&limit={page_size}&offset={offset}",
            headers=UA
        ))
        total = resp['release-count']
        batch = resp['releases']
        releases.extend(batch)
        offset += len(batch)
        if offset < total:
            time.sleep(1)  # stay within 1 req/s for sequential pagination
    return releases

# Queen has 1635 releases — use release-groups (412) to get deduplicated albums

`inc=` parameter reference

Stack multiple inc= values with + between them.

Artist lookup (/ws/2/artist/{mbid}):

releases — list of releases (max ~25)
release-groups — list of release groups (max ~25)
recordings — list of recordings (max ~25)
works — list of works
tags — community genre tags (name + vote count)
ratings — community rating (value 0-5, votes-count)
aliases — alternative names and transliterations
annotation — free-text editorial note
artist-rels, release-rels, recording-rels, work-rels — relationship data

Release lookup (/ws/2/release/{mbid}):

artists — full artist-credit objects
recordings — track list with recording links (populates media[].tracks[].recording)
labels — label-info with catalog numbers
release-groups — the release group this belongs to
artist-credits — expanded artist credit with joinphrase
media — disc/format info (always included in lookup, not needed in inc=)

Response shapes cheat sheet

code

# MBID format: standard UUID v4
"0383dadf-2a4e-4d10-a46a-e9e041da8eb3"

# Search response (artist/recording/release/release-group/label/work)
{
  "count": 1612,          # total matches
  "offset": 0,
  "<entity-plural>": [...] # e.g. "artists", "releases", "recordings", "release-groups"
}

# Browse response (using ?artist=MBID or ?label=MBID style)
{
  "release-count": 1635,  # note: key name changes per entity
  "release-offset": 0,    # e.g. "release-group-count", "recording-count"
  "releases": [...]
}

# Recording length is always milliseconds
recording['length'] // 1000  # => seconds

# Artist life-span
life_span = artist['life-span']
# {'begin': '1970-06-27', 'end': None, 'ended': True}
# 'ended': True with 'end': None means end date unknown but band is inactive

# Artist credit joinphrase (for multi-artist tracks)
# [{"name": "Simon", "artist": {...}, "joinphrase": " & "}, {"name": "Garfunkel", ...}]

URL patterns

Resource	URL
Artist search	`https://musicbrainz.org/ws/2/artist/?query={q}&fmt=json&limit=5`
Artist by MBID	`https://musicbrainz.org/ws/2/artist/{mbid}?inc=tags+ratings&fmt=json`
Browse releases by artist	`https://musicbrainz.org/ws/2/release/?artist={mbid}&fmt=json&limit=25&offset=0`
Release search	`https://musicbrainz.org/ws/2/release/?query={q}&fmt=json&limit=5`
Release by MBID	`https://musicbrainz.org/ws/2/release/{mbid}?inc=artists+recordings+labels&fmt=json`
Release-group browse	`https://musicbrainz.org/ws/2/release-group/?artist={mbid}&fmt=json&limit=25`
Recording search	`https://musicbrainz.org/ws/2/recording/?query={q}&fmt=json&limit=5`
Label search	`https://musicbrainz.org/ws/2/label/?query={q}&fmt=json&limit=5`
Work search	`https://musicbrainz.org/ws/2/work/?query={q}&fmt=json&limit=5`
Cover art	`https://coverartarchive.org/release/{release-mbid}`

MusicBrainz entity browser URL (human-readable): https://musicbrainz.org/artist/{mbid} (replace artist with release, recording, etc.)

Gotchas

User-Agent is mandatory — without it you get HTTP 403 instantly. The header must include contact info, e.g. browser-harness/1.0 (you@example.com). The default http_get UA (Mozilla/5.0) also gets 403.
Browse vs search response keys differ — Search responses use count and offset; Browse responses (with ?artist=MBID) use release-count / release-offset (or release-group-count etc.). Accessing data['count'] on a browse response throws KeyError.
releases include in artist lookup caps at ~25 — Use the browse endpoint (?artist=MBID) with pagination for complete lists. Queen has 1,635 releases total; the inc=releases on the artist endpoint only returns ~25.
Use release-groups to avoid edition explosion — A popular album can have hundreds of release entries (every country's pressing, every remaster, every format). Use /ws/2/release-group/ to get one entry per "album concept". Queen's "A Night at the Opera" has 75+ release entries but 1 release-group.
Recording length is milliseconds — recording['length'] is in milliseconds, not seconds. Divide by 1000.
Sort-name differs from display name for persons — Artists have both name (display: "David Bowie") and sort-name (alphabetical: "Bowie, David"). Groups usually have identical values.
Disambiguation in parentheses — When multiple entities share a name, MusicBrainz adds a disambiguation field to distinguish them (e.g. "English singer-songwriter" vs a different David Bowie). Always check a.get('disambiguation', '') when resolving artist identity.
Score 100 does not mean unique — Search returns score: 100 for multiple results when several equally match the query. "dark side of the moon" returns 6 results all scored 100 — they're different regional pressings. Filter by date, country, or status to narrow down.
Recording search: plain query matches titles AND artists broadly — ?query=bohemian+rhapsody+queen matches cover versions first because "queen" appears in the artist or title of other recordings. Use AND artist:queen Lucene syntax to restrict to Queen performances.
Cover Art Archive returns 404 for releases with no uploaded art — Check release['cover-art-archive']['artwork'] (boolean) from any release browse/search response before hitting the CAA endpoint. Saves an extra HTTP round-trip.
Cover art front=True flag vs types=['Front'] — A release can have multiple images typed as 'Front' but only one (or none) flagged front: true. Always filter on img.get('front') == True for the canonical cover, not on img.get('types') == ['Front'].
CAA thumbnail key names — Both string keys 'small' (250px) and 'large' (500px) exist as aliases alongside numeric string keys '250', '500', '1200'. Access as img['thumbnails']['500'] or img['thumbnails']['large'] — both work.
Rate limit: 1 req/s unauthenticated — In practice, bursts of 5-6 sequential requests succeed without throttling. True 429s appear at higher rates. For sequential pagination loops, add time.sleep(1) between pages. For parallel fetching, limit concurrency to 3-5 workers.
fmt=json required — Omitting it returns XML instead of JSON. Always append &fmt=json to every request.

musicbrainz

Use this skill

What the agent will read

Data Extraction

Do this first

Entity types

Common workflows

Artist search

Artist by MBID (with related data via `inc=`)

Browse releases by artist (full list)

Release search and lookup

Recording (track) search

Release-group search (deduplicated albums)

Label and work lookups

Cover Art Archive

Lucene query syntax for search

Parallel fetching

Pagination

`inc=` parameter reference

Response shapes cheat sheet

URL patterns

Gotchas

Use this skill

What the agent will read

Data Extraction

Do this first

Entity types

Common workflows

Artist search

Artist by MBID (with related data via inc=)

Browse releases by artist (full list)

Release search and lookup

Recording (track) search

Release-group search (deduplicated albums)

Label and work lookups

Cover Art Archive

Lucene query syntax for search

Parallel fetching

Pagination

inc= parameter reference

Response shapes cheat sheet

URL patterns

Gotchas

Artist by MBID (with related data via `inc=`)

`inc=` parameter reference