# Metal Archives — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search and explore music data including bands, albums, songs, and lyrics, with the ability to discover artist recommendations, view band members and discographies, and look up record label information. Get detailed information about musicians, their releases, and recommendations based on your musical interests.

**Category:** Music | **Website:** [metal-archives.com/](https://metal-archives.com/) | **Docs:** [parse.bot/marketplace/13434b14-c019-43df-8182-fa0619216c4a/metal-archives-com-api](https://parse.bot/marketplace/13434b14-c019-43df-8182-fa0619216c4a/metal-archives-com-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/metal-archives/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Get album details

Fetch full details for an album including tracklist with song IDs for lyrics lookup. The album_id comes from search_albums or get_band_discography.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `album_id` | string | Yes | Numeric album ID (from search_albums results[*].album_id or get_band_discography discography[*].id). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/metal-archives/get-album-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"album_id":"<string>"}'
```

### Get artist details

Fetch full details for an artist/musician including biography and personal information. The artist_id comes from get_band_members results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `artist_id` | string | Yes | Numeric artist ID (from get_band_members current/past/live[*].id). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/metal-archives/get-artist-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"artist_id":"<string>"}'
```

### Get band details

Fetch full details for a single band by its numeric ID. Returns genre, country, biography, label, status, and years active. The band_id comes from search_bands results or any other endpoint that references bands.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `band_id` | string | Yes | Numeric band ID (from search_bands results[*].id). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/metal-archives/get-band-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"band_id":"<string>"}'
```

### Get band discography

Fetch the discography for a band, optionally filtered by release type. Returns an array of releases with name, type, year, and review score. Returns an empty array if the band has no releases of the requested type.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `band_id` | string | Yes | Numeric band ID (from search_bands results[*].id). |
| `tab` | string | No | Filter by release type. Accepted values: all, main, lives, demos, misc. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/metal-archives/get-band-discography \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"band_id":"<string>","tab":"<string>"}'
```

### Get band members

Fetch the current, past, and live/session members for a band. Each member entry includes name, role, and artist_id for drill-down via get_artist_details.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `band_id` | string | Yes | Numeric band ID (from search_bands results[*].id). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/metal-archives/get-band-members \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"band_id":"<string>"}'
```

### Get band recommendations

Fetch similar artist recommendations for a band, ordered by similarity score. Each recommendation includes band name, country, genre, and a numeric similarity score.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `band_id` | string | Yes | Numeric band ID (from search_bands results[*].id). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/metal-archives/get-band-recommendations \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"band_id":"<string>"}'
```

### Get label details

Fetch record label details including address, status, and specialties. The label_id is a numeric identifier.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `label_id` | string | Yes | Numeric label ID. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/metal-archives/get-label-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"label_id":"<string>"}'
```

### Get label roster

Fetch bands signed to a label with pagination. Can retrieve either the current or past roster.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `label_id` | string | Yes | Numeric label ID. |
| `limit` | integer | No | Max results to return per page. |
| `offset` | integer | No | Pagination offset (number of results to skip). |
| `past` | boolean | No | If true, fetch the past roster instead of the current roster. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/metal-archives/get-label-roster \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"label_id":"<string>","limit":"<integer>","offset":"<integer>","past":"<boolean>"}'
```

### Get lyrics

Fetch lyrics for a song by its song ID. The song_id comes from get_album_details tracklist[*].song_id. Returns empty lyrics string if no lyrics are available for that song.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `song_id` | string | Yes | Song ID from get_album_details tracklist[*].song_id. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/metal-archives/get-lyrics \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"song_id":"<string>"}'
```

### Search albums

Full-text search over album/release titles. Returns paginated results with album title, band name, and release type. Each result carries album_id and band_id for drill-down.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Max results to return per page. |
| `offset` | integer | No | Pagination offset (number of results to skip). |
| `query` | string | Yes | Album title to search for. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/metal-archives/search-albums \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","offset":"<integer>","query":"<string>"}'
```

### Search bands

Full-text search over metal band names. Returns paginated results with band name, genre, and country. Each result carries a band ID usable with get_band_details, get_band_discography, get_band_members, and get_band_recommendations.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Max results to return per page. |
| `offset` | integer | No | Pagination offset (number of results to skip). |
| `query` | string | Yes | Band name to search for. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/metal-archives/search-bands \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","offset":"<integer>","query":"<string>"}'
```

### Search songs

Full-text search over song titles. Returns paginated results with song title, band, album, and lyrics availability. Each result carries band_id and album_id for drill-down.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Max results to return per page. |
| `offset` | integer | No | Pagination offset (number of results to skip). |
| `query` | string | Yes | Song title to search for. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/metal-archives/search-songs \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","offset":"<integer>","query":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.