Skip to the content
  1. API reference
  2. Recommendations

Recommend the next tracks

POST/public/recommendations/next
CoreAuthBasicTokenDevTokenDocsSession

The next tracks of a listening session. recent lists the tracks just played, newest first; newer tracks count more. skipped steers away. With userId, the listener's taste counts too (30%). The answer never holds recent, skipped or exclude. With userId, the call needs Client Secret authentication, and an answered call counts the listener as a personalised user of the month. Without userId, any credential works.

Request body

application/json · required

userId
string
Your own id of the listener. Optional.
recent
string[]
The ISRCs just played, newest first.
skipped
string[]
ISRCs the listener skipped in this session.
exclude
string[]
ISRCs to leave out.
limit
number
Default: 20
catalogue
string
The id of one of your catalogues.
maxPerArtist
number
Default: 2

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 malformed ISRC, or a list or limit out of range.

401

No valid credential.

403

userId is set, and the request does not use Client Secret authentication.

404

no_signal: no recent track has a vector and the listener has no usable events. 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.