metal-archives.com APImetal-archives.com ↗
Access Metal Archives band details, discographies, lyrics, artist bios, and label rosters via 12 structured endpoints. Search bands, albums, and songs by name.
curl -X GET 'https://api.parse.bot/scraper/b08fc1e3-313a-4420-8e34-14bd3568c8d1/search_bands?limit=200&query=Iron+Maiden&offset=0' \ -H 'X-API-Key: $PARSE_API_KEY'
Search for bands by name. Returns paginated results with band name, genre, and country.
| Param | Type | Description |
|---|---|---|
| limit | integer | Max results to return per page. |
| queryrequired | string | Band name to search for. |
| offset | integer | Pagination offset (number of results to skip). |
{
"type": "object",
"fields": {
"limit": "integer limit used",
"total": "integer total number of matching bands",
"offset": "integer pagination offset used",
"results": "array of band objects with name, url, id, genre, and country"
},
"sample": {
"data": {
"limit": 200,
"total": 1,
"offset": 0,
"results": [
{
"id": "25",
"url": "https://www.metal-archives.com/bands/Iron_Maiden/25",
"name": "Iron Maiden",
"genre": "Heavy Metal, NWOBHM",
"country": "United Kingdom"
}
]
},
"status": "success"
}
}About the metal-archives.com API
The Metal Archives API exposes 12 endpoints covering the full depth of the Encyclopaedia Metallum database — bands, albums, songs, lyrics, artists, and record labels. Use search_bands to find acts by name with genre and country in each result, get_band_discography to pull a filtered release timeline, or get_lyrics to retrieve song text by ID. Band, album, artist, and label data are all cross-linked through shared numeric IDs.
Band and Discography Data
The get_band_details endpoint returns a band's bio, genre, status, themes, country, location, formed_in, and logo_url given a numeric band_id (sourced from search_bands results). get_band_discography accepts an optional tab parameter — all, main, lives, demos, or misc — and returns an array of releases each containing name, type, year, and a reviews field. get_band_members splits the roster into current, past, and live arrays, with each member carrying their own numeric id for downstream artist lookups.
Album and Song Data
get_album_details returns a tracklist where every track includes a song_id that feeds directly into get_lyrics. The album object also exposes type (Full-length, EP, Demo, etc.), label, format, catalog_id, and release_date. search_songs lets you query by title and returns lyrics_status alongside band and album cross-references, so you can check whether lyrics are available before fetching them.
Artist and Label Data
get_artist_details returns personal fields including real_name, age, gender, place_of_birth, and bio for individual musicians. On the label side, get_label_details surfaces address, phone, founded, specialties, status, and online_shopping. get_label_roster supports past (boolean) and paginated lookups via limit and offset, returning each signed band with name, genre, and country. Label IDs are not currently returned by band detail endpoints, so you will need a label ID from external context or from the label field in get_album_details.
Search and Recommendations
All three search endpoints — search_bands, search_albums, and search_songs — return total, offset, and limit alongside results, enabling straightforward pagination. get_band_recommendations returns similar bands ordered by a score field, each with name, country, genre, and a direct id for further lookups.
- Build a metal band encyclopedia that shows biography, genre, formed year, and logo from
get_band_details. - Generate a band's full release timeline filtered by demo or live recordings using
get_band_discographywith thetabparameter. - Display song lyrics in a music player app by chaining
get_album_detailstracklistsong_idvalues intoget_lyrics. - Map musician career histories by pulling
pastandcurrentmembers fromget_band_membersand resolving each viaget_artist_details. - Recommend similar bands in a discovery app using the
score-sorted results fromget_band_recommendations. - Audit a record label's current and historical artist roster with
get_label_rosterusing thepastboolean and pagination. - Index searchable song metadata including
lyrics_statusacross a large catalogue usingsearch_songswith paginated offsets.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 250 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Metal Archives have an official developer API?+
How do I retrieve lyrics, and what does `lyrics_status` tell me in search results?+
get_lyrics requires a song_id, which you get from the tracklist array in get_album_details — each track object includes number, title, duration, and song_id. The lyrics_status field returned by search_songs indicates whether lyrics are present for a given song before you commit a lookup, helping avoid empty requests.Can I look up a band's label ID directly from band detail or search endpoints?+
get_band_details returns only a label name string, not a numeric label ID. get_album_details returns the label name in the label field but also does not include a numeric label ID. Currently, direct label-ID resolution from band or album endpoints is not supported. You can fork this API on Parse and revise it to add a label search or label-ID lookup endpoint.Does the API expose band images beyond the logo?+
get_band_details returns a logo_url field. Band photo galleries or additional image assets are not currently included in any endpoint response. You can fork this API on Parse and revise it to add an endpoint returning band photo URLs.How does pagination work across the search and roster endpoints?+
search_bands, search_albums, search_songs, and get_label_roster — return total, offset, and limit in every response. Pass offset as the number of results to skip and limit to control page size. total gives you the full match count so you can calculate how many pages exist without a separate call.