- Docs
- Recommendations
Personal recommendations
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.
| Task | Endpoint |
|---|---|
| Send listening events | POST/public/recommendations/events |
| Recommendations for one user | GET/public/recommendations/users/{userId}/recommendations |
| The next tracks of a session | POST/public/recommendations/next |
| Delete everything about one user | DEL/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 -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" }
]
}'
{ "accepted": 3, "rejected": [] }
Your id of the user, 1 to 128 characters.
The track. An ISRC that MusicAPI does not know is accepted and stored: a later model can know it.
play, complete, like, skip or dislike.
When it happened.
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
413withpayload_too_large. More than 1,000 events answers400. - 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:
type | Weight |
|---|---|
like | 3 |
complete | 1.5 |
play | 1, 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 "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 -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
}'
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.
Up to 50 ISRCs that the user skipped in the session. They push the answer away.
Blends in the user's taste from the events. Needs the Client Secret.
Up to 1,000 ISRCs that must not come back.
1 to 50.
1 to 100.
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 withuserIdneeds the Client Secret, so send it from your backend. - Without
userId, the session alone decides. Then the call works with every credential, alsoToken <clientId>in an app. recent,skipped,excludeand the tracks of the user's last events never come back.- When nothing resolves to a vector, the answer is
404withno_signal.
The answer is { "modelVersion": "…", "tracks": [ … ] }. It is not cached.
Delete a user (GDPR)
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 /eventsaccepted at least one event of the user;GET /users/{userId}/recommendationsanswered;POST /nextwith thatuserIdanswered.
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.