Skip to the content
  1. API reference
  2. Recommendations

Recommend tracks for a listener

GET/public/recommendations/users/{userId}/recommendations
CoreAuthBasic

Tracks for one listener, from the events you sent for them. Recent events count more (half-life 30 days); a like counts most, a dislike pushes away. Tracks the listener already has in their last 500 events are left out. A listener without usable events answers 404 no_signal. Each answered call counts the listener as a personalised user of the month. Needs Client Secret authentication.

Path parameters

userId
stringrequired

Your own id of the listener, 1 to 128 characters. We store it only under your account.

Query parameters

limit
number · 20

How many tracks to return.

catalogue
string

The id of one of your catalogues. Results then come only from that catalogue. Leave it out for the whole MusicAPI catalogue.

maxPerArtist
number · 2

At most this many tracks of one artist.

Response

200application/json · RecommendationTracksResponseok
modelVersion
string
required
tracks
RecommendationTrack[]
required
tracks[].isrc
string
requiredWith catalogue: your own ISRC of the track. Else one ISRC of the track.
tracks[].score
number
requiredThe similarity to the seeds, up to 1.
tracks[].title
string | null
requiredA display aid. Your own metadata stays the source of truth.
tracks[].artist
object
required
tracks[].artist.id
string
requiredThe MusicAPI artist id. Use it as an artist seed.
tracks[].artist.name
string | null
required
Example answer
{
  "modelVersion": "2026-11-13",
  "tracks": [
    {
      "isrc": "USRC17607839",
      "score": 0.8731,
      "title": "Forests",
      "artist": {
        "id": "123456",
        "name": "LaziiBee"
      }
    }
  ]
}

Errors

400

A parameter is out of range.

401

No valid credential.

403

The request does not use Client Secret authentication.

404

no_signal: no usable events for this listener. catalogue_not_found: the catalogue does not exist or is not yours.

409

catalogue_not_ready: the catalogue is still processing.

429

Your account sent more calls this minute than its rate limit allows.

503

model_not_ready: no recommendation model is active yet. Try again later. temporarily_unavailable: the recommendation index is loading or busy (for example right after a weekly model swap). Try again after the Retry-After seconds.