Skip to the content
  1. Docs
  2. Recommendations

Personal recommendations

CoreGuide · 4 min
Send the listening events of your users, then get recommendations for one user or the next tracks of a session. Event kinds and limits, the session blend, the GDPR delete and the personalised-user meter.

The Recommendations API can learn the taste of each of your users. You send what a user plays, likes and skips. The API then recommends tracks for that user, or the next tracks of a listening session.

TaskEndpoint
Send listening eventsPOST/public/recommendations/events
Recommendations for one userGET/public/recommendations/users/{userId}/recommendations
The next tracks of a sessionPOST/public/recommendations/next
Delete everything about one userDEL/public/recommendations/users/{userId}

userId is your own id of the user: any string of 1 to 128 characters. MusicAPI stores it as you send it. Use an opaque id, not an email address or a name. A user id belongs to your account only: another account with the same id sees nothing of your user.

Send events

POST /public/recommendations/events needs Basic clientId:clientSecret. Send events from your server, in batches.

curl
curl -X POST "https://api.musicapi.com/public/recommendations/events" \
  -u "$MUSICAPI_CLIENT_ID:$MUSICAPI_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "userId": "u_8841", "isrc": "USRC17607839", "type": "play", "at": "2026-11-16T09:12:00Z", "msPlayed": 184000 },
      { "userId": "u_8841", "isrc": "GBUM71029604", "type": "skip", "at": "2026-11-16T09:15:10Z", "msPlayed": 6000 },
      { "userId": "u_8841", "isrc": "USUM71703861", "type": "like", "at": "2026-11-16T09:16:02Z" }
    ]
  }'
202 Accepted
{ "accepted": 3, "rejected": [] }
userId
stringrequired

Your id of the user, 1 to 128 characters.

isrc
stringrequired

The track. An ISRC that MusicAPI does not know is accepted and stored: a later model can know it.

type
stringrequired

play, complete, like, skip or dislike.

at
string (ISO 8601)required

When it happened.

msPlayed
integer · 0

How long the track played, 0 to 86,400,000 ms. A play under 30 seconds counts half.

Limits:

  • Up to 1,000 events per call, and a body of up to 1 MiB. A larger body answers 413 with payload_too_large. More than 1,000 events answers 400.
  • An event more than 5 minutes in the future, or older than 400 days, is rejected. The others of the call are stored. Each rejected event comes back with its position in the list and the reason: { "index": 4, "reason": "in_future" } or "too_old".
  • An accepted event is stored when the answer arrives. The next recommendation for that user already uses it.

How events count

The user's taste is the weighted mean of the tracks of the user's last 500 events:

typeWeight
like3
complete1.5
play1, or 0.5 under 30 seconds
skip-1
dislike-3

An event loses half of its weight every 30 days, so new events count more. Only events whose track has a vector count. The tracks of the last 500 events never come back in a recommendation for the user.

Recommendations for one user

curl
curl "https://api.musicapi.com/public/recommendations/users/u_8841/recommendations?limit=20" \
  -u "$MUSICAPI_CLIENT_ID:$MUSICAPI_CLIENT_SECRET"

The query takes limit (1 to 100, default 20), maxPerArtist (1 to 100, default 2) and catalogue (one of your catalogue ids). The answer is { "modelVersion": "…", "tracks": [ … ] }, with tracks in the same shape as GET /similar-tracks.

This endpoint needs the Client Secret. A user with no event that counts answers 404 with no_signal. These answers are not cached, so they follow new events at once.

The next tracks of a session

POST /public/recommendations/next picks what to play next, from what the user just heard.

curl
curl -X POST "https://api.musicapi.com/public/recommendations/next" \
  -u "$MUSICAPI_CLIENT_ID:$MUSICAPI_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "u_8841",
    "recent": ["USUM71703861", "USRC17607839"],
    "skipped": ["GBUM71029604"],
    "limit": 10
  }'
recent
string[]

Up to 50 ISRCs of the session, the newest first. The newest counts most: each track counts 0.85 times the track before it in the list.

skipped
string[]

Up to 50 ISRCs that the user skipped in the session. They push the answer away.

userId
string

Blends in the user's taste from the events. Needs the Client Secret.

exclude
string[]

Up to 1,000 ISRCs that must not come back.

limit
integer · 20

1 to 50.

maxPerArtist
integer · 2

1 to 100.

catalogue
string

One of your catalogue ids. Leave it out for the whole MusicAPI catalogue.

  • With userId, the query is 0.7 × the session and 0.3 × the user's taste. When only one of them exists, the API uses that one. A call with userId needs the Client Secret, so send it from your backend.
  • Without userId, the session alone decides. Then the call works with every credential, also Token <clientId> in an app.
  • recent, skipped, exclude and the tracks of the user's last events never come back.
  • When nothing resolves to a vector, the answer is 404 with no_signal.

The answer is { "modelVersion": "…", "tracks": [ … ] }. It is not cached.

Delete a user (GDPR)

curl
curl -X DELETE "https://api.musicapi.com/public/recommendations/users/u_8841" \
  -u "$MUSICAPI_CLIENT_ID:$MUSICAPI_CLIENT_SECRET"

The answer is 204. The call deletes every event of the user in your account and the user's cached taste. The next recommendation for the user answers no_signal until you send new events. The meter rows of the days the user was already counted stay, because that usage already happened.

Call it when the user deletes their account or asks you to erase their data.

Billing

The personalised-user meter counts each distinct userId of your account once per calendar month (UTC). A user counts in a month when one of these succeeded for the user:

  • POST /events accepted at least one event of the user;
  • GET /users/{userId}/recommendations answered;
  • POST /next with that userId answered.

A call that fails does not count the user. POST /next without userId counts no user. These endpoints do not count on the request meter. See Billing.