Skip to the content
  1. API reference
  2. Recommendations

Recommend similar tracks

GET/public/recommendations/similar-tracks
CoreAuthBasicTokenDevTokenDocsSession

Finds tracks that listeners put next to the seed track, from playlist co-occurrence across music services. No audio is analysed. The seed itself is never in the answer. basis says what the answer is built on: track (the track's own vector) or artist (the track has no vector yet, so its artist's vector is used). With catalogue, every result is in that catalogue. Answers are cached for a model version. Each call counts as one recommendation request on your usage.

Query parameters

isrc
stringrequired

The seed track's ISRC: 12 characters. Dashes, spaces and lower case are accepted. Any ISRC of the track works.

catalogue
string

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

limit
number · 20

How many results to return.

maxPerArtist
number · 2

At most this many tracks of one artist.

excludeSameArtist
boolean · false

Leave out every track of the seed's artist.

Response

200application/json · RecommendationSimilarTracksResponseok
modelVersion
string
requiredThe model version that made the answer.
basis
string
requiredWhat the answer is built on: the track's own vector, or its artist's vector.One of: track, artist, genre
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",
  "basis": "track",
  "tracks": [
    {
      "isrc": "USRC17607839",
      "score": 0.8731,
      "title": "Forests",
      "artist": {
        "id": "123456",
        "name": "LaziiBee"
      }
    }
  ]
}

Errors

400

The ISRC is not a 12-character ISRC, or a parameter is out of range.

401

No valid credential.

404

no_signal: the seed ISRC has no vector and its artist has none either. 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.