# ListenBrainz API
> A live window into ListenBrainz — the open, MetaBrainz-run music-scrobbling social network, the open-data answer to Last.fm — as an API. Pull the sitewide listening charts: the most-listened artists, recordings or releases over a week, month, quarter, year or all time, each with its listen count; a user's most recent listens; or what a user is playing right now. The pulse of what the open-music community is listening to, delivered as clean JSON for music, social and dashboard apps. Live data, no key. Distinct from music-metadata and lyrics APIs.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/listenbrainz-api/..."
```

## Pricing
- **Free** (Free) — 600 calls/Mo, 5 req/s
- **Starter** ($6/Mo) — 14,000 calls/Mo, 15 req/s
- **Pro** ($16/Mo) — 68,000 calls/Mo, 30 req/s
- **Business** ($41/Mo) — 340,000 calls/Mo, 50 req/s

## Endpoints

### Charts

#### `GET /v1/charts` — Sitewide listening charts

**Parameters:**
- `entity` (query, optional, string) — artists (default), recordings or releases Example: `artists`
- `range` (query, optional, string) — week (default), month, quarter, year or all_time Example: `week`
- `count` (query, optional, string) — Max results (1-100) Example: `25`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/listenbrainz-api/v1/charts?entity=artists&range=week&count=25"
```

**Response:**
```json
{
    "data": {
        "count": 25,
        "range": "week",
        "charts": [
            {
                "mbid": "69158f97-4c07-4c4e-baf8-4e4ab1ed666e",
                "name": "Boards of Canada",
                "rank": 1,
                "title": null,
                "artist": "Boards of Canada",
                "listen_count": 33354
            },
            {
                "mbid": "f59c5520-5f46-4d2c-b2c4-822eabf53419",
                "name": "Linkin Park",
                "rank": 2,
                "title": null,
                "artist": "Linkin Park",
                "listen_count": 17407
            },
            {
                "mbid": "a74b1b7f-71a5-4011-9441-d0b5e4122711",
                "name": "Radiohead",
                "rank": 3,
                "title": null,
                "artist": "Radiohead",
                "listen_count": 13545
            },
            {
                "mbid": "9fff2f8a-21e6-47de-a2b8-7f449929d43f",
                "name": "Drake",
                "rank": 4,
                "title": null,
                "artist": "Drake",
                "listen_count": 12043
            },
            {
                "mbid": "20244d07-534f-4eff-b4d4-930878889970",
                "name": "Taylor Swift",
                "rank": 5,
                "title": null,
                "artist": "Taylor Swift",
                "listen_count": 11600
            },
            {
                "mbid": "164f0d73-1234-4e2c-8743-d77bf2191051",
…(truncated, see openapi.json for full schema)
```

### Users

#### `GET /v1/now-playing` — What a user is playing now

**Parameters:**
- `username` (query, required, string) — ListenBrainz username Example: `rob`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/listenbrainz-api/v1/now-playing?username=rob"
```

**Response:**
```json
{
    "data": {
        "track": null,
        "username": "rob",
        "playing_now": false
    },
    "meta": {
        "timestamp": "2026-06-09T03:03:26.257Z",
        "request_id": "8b8efc82-034d-47d5-8323-3378f3073d26"
    },
    "status": "ok",
    "message": "Now playing retrieved successfully",
    "success": true
}
```

#### `GET /v1/similar-users` — Users with the most similar listening taste

**Parameters:**
- `username` (query, required, string) — ListenBrainz username Example: `rob`
- `count` (query, optional, string) — Max users (1-100) Example: `25`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/listenbrainz-api/v1/similar-users?username=rob&count=25"
```

**Response:**
```json
{
    "data": {
        "count": 25,
        "username": "rob",
        "similar_users": [
            {
                "username": "Violet&Red",
                "similarity": 0.4739
            },
            {
                "username": "carbonokabe",
                "similarity": 0.23
            },
            {
                "username": "spacetripcorp",
                "similarity": 0.1961
            },
            {
                "username": "mcc1979",
                "similarity": 0.1864
            },
            {
                "username": "musicbosun",
                "similarity": 0.1753
            },
            {
                "username": "TheNoNinja",
                "similarity": 0.1646
            },
            {
                "username": "LexIram",
                "similarity": 0.1514
            },
            {
                "username": "vonmartins",
                "similarity": 0.1489
            },
            {
                "username": "boldengoy",
                "similarity": 0.1344
            },
            {
                "username": "bjorkalx",
                "similarity": 0.126
            },
            {
                "username": "decent7830",
                "similarity": 0.1199
            },
            {
                "username": "gb228",
                "similarity": 0.1187
            },
            {
                "username": "scrafi",
                "similarity": 0.1186
            },
            {
        
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/user` — A user's recent listens

**Parameters:**
- `username` (query, required, string) — ListenBrainz username Example: `rob`
- `count` (query, optional, string) — Max listens (1-100) Example: `25`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/listenbrainz-api/v1/user?username=rob&count=25"
```

**Response:**
```json
{
    "data": {
        "count": 25,
        "listens": [
            {
                "track": "Some Resolve",
                "artist": "Röyksopp",
                "release": "Profound Mysteries II",
                "listened_at": "2026-02-18T11:28:29.000Z",
                "recording_mbid": "30d08f4c-d825-4ae1-b79c-44242cddd7c0"
            },
            {
                "track": "Tell Him",
                "artist": "Röyksopp feat. Susanne Sundfør",
                "release": "Profound Mysteries II",
                "listened_at": "2026-02-18T11:21:46.000Z",
                "recording_mbid": "46f0b53f-6731-457c-93e7-57cff0e5b0c2"
            },
            {
                "track": "Remembering the Departed",
                "artist": "Röyksopp",
                "release": "Profound Mysteries II",
                "listened_at": "2026-02-18T11:16:20.000Z",
                "recording_mbid": "a8eb2940-b706-4e35-afd2-f15feec4eb20"
            },
            {
                "track": "It Was a Good Thing",
                "artist": "Röyksopp feat. Pixx",
                "release": "Profound Mysteries II",
                "listened_at": "2026-02-18T11:12:30.000Z",
                "recording_mbid": "100bdac3-db86-41ba-b987-6f639914834c"
            },
            {
                "track": "Control",
                "artist": "Röyksopp",
                "release": "Profound Mysteries II",
                "listened_at": "2026-02-18T11:08:17.000Z",
                "reco
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/user-stats` — A user's top artists, recordings or releases

**Parameters:**
- `username` (query, required, string) — ListenBrainz username Example: `rob`
- `entity` (query, optional, string) — artists (default), recordings or releases Example: `artists`
- `range` (query, optional, string) — all_time (default), week, month, quarter or year Example: `all_time`
- `count` (query, optional, string) — Max results (1-100) Example: `25`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/listenbrainz-api/v1/user-stats?username=rob&entity=artists&range=all_time&count=25"
```

**Response:**
```json
{
    "data": {
        "count": 25,
        "range": "all_time",
        "stats": [
            {
                "mbid": "c24b47a1-2f52-44f3-a3c6-374dca844731",
                "name": "Wax Tailor",
                "rank": 1,
                "title": null,
                "artist": "Wax Tailor",
                "listen_count": 4298
            },
            {
                "mbid": "1c70a3fc-fa3c-4be1-8b55-c3192db8a884",
                "name": "Röyksopp",
                "rank": 2,
                "title": null,
                "artist": "Röyksopp",
                "listen_count": 4249
            },
            {
                "mbid": "a8b39181-6939-451e-9641-2db231b73706",
                "name": "Abakus",
                "rank": 3,
                "title": null,
                "artist": "Abakus",
                "listen_count": 3809
            },
            {
                "mbid": "9a709693-b4f8-4da9-8cc1-038c911a61be",
                "name": "Bonobo",
                "rank": 4,
                "title": null,
                "artist": "Bonobo",
                "listen_count": 3536
            },
            {
                "mbid": "3a07764c-7cc5-42e9-8205-3de7532f4771",
                "name": "Pretty Lights",
                "rank": 5,
                "title": null,
                "artist": "Pretty Lights",
                "listen_count": 3183
            },
            {
                "mbid": "8229a8f1-b315-4fae-af57-b3eb71efdaf4",
                "na
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Service metadata

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/listenbrainz-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "ranges": [
            "week",
            "month",
            "quarter",
            "year",
            "all_time"
        ],
        "source": "ListenBrainz public API (live)",
        "service": "listenbrainz-api",
        "entities": [
            "artists",
            "recordings",
            "releases"
        ],
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/user": "A user's recent listens (username=, e.g. rob, count).",
            "GET /v1/charts": "Sitewide listening charts (entity=artists|recordings|releases, range=week|month|quarter|year|all_time, count).",
            "GET /v1/now-playing": "What a user is playing now (username=)."
        },
        "description": "Live data from ListenBrainz, the open MetaBrainz music-scrobbling network: sitewide listening charts (most-listened artists, recordings or releases by week/month/year/all-time with listen counts), a user's recent listens, and what a user is playing now. Live, no key. Distinct from music-metadata and lyrics APIs.",
        "upstream_status": "ok"
    },
    "meta": {
        "timestamp": "2026-06-09T03:03:27.829Z",
        "request_id": "0d5cc58f-a409-4434-8553-e6c8bef09a89"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```

### Artists

#### `GET /v1/artist-listeners` — The top listeners of an artist by MusicBrainz id

**Parameters:**
- `artist_mbid` (query, required, string) — MusicBrainz artist id Example: `a74b1b7f-71a5-4011-9441-d0b5e4122711`
- `range` (query, optional, string) — all_time (default), week, month, quarter or year Example: `all_time`
- `count` (query, optional, string) — Max listeners (1-100) Example: `25`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/listenbrainz-api/v1/artist-listeners?artist_mbid=a74b1b7f-71a5-4011-9441-d0b5e4122711&range=all_time&count=25"
```

**Response:**
```json
{
    "data": {
        "count": 9,
        "range": "all_time",
        "artist": "Radiohead",
        "listeners": [
            {
                "username": "PixelGRM",
                "listen_count": 135184
            },
            {
                "username": "bullofheaven",
                "listen_count": 44456
            },
            {
                "username": "keir2",
                "listen_count": 23261
            },
            {
                "username": "frazda",
                "listen_count": 20491
            },
            {
                "username": "mischiamnesiac",
                "listen_count": 20203
            },
            {
                "username": "Mergzo",
                "listen_count": 18242
            },
            {
                "username": "florianec",
                "listen_count": 17349
            },
            {
                "username": "arkruffian",
                "listen_count": 17252
            },
            {
                "username": "duncethethird",
                "listen_count": 16768
            }
        ],
        "artist_mbid": "a74b1b7f-71a5-4011-9441-d0b5e4122711",
        "total_listens": 6568747,
        "total_listeners": null
    },
    "meta": {
        "timestamp": "2026-06-13T14:11:34.419Z",
        "request_id": "21e30aa4-ceb1-4ba3-bc06-b570a4abc22b"
    },
    "status": "ok",
    "message": "Artist listeners retrieved successfully",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/listenbrainz-api
OpenAPI spec: https://www.oanor.com/api/listenbrainz-api/openapi.json