# Personal recommendations
URL: https://musicapi.com/docs/recommendations/personal-recommendations.md

> 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.

Product: MusicAPI Core. Section: Recommendations.

The [Recommendations API](https://musicapi.com/docs/recommendations/recommendations.md) 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`](https://musicapi.com/docs/reference/recommendations-send-events.md)                     |
| Recommendations for one user     | [`GET /public/recommendations/users/{userId}/recommendations`](https://musicapi.com/docs/reference/recommendations-for-user.md) |
| The next tracks of a session     | [`POST /public/recommendations/next`](https://musicapi.com/docs/reference/recommendations-next.md)                              |
| Delete everything about one user | [`DELETE /public/recommendations/users/{userId}`](https://musicapi.com/docs/reference/recommendations-delete-user.md)           |

`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.

```bash
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" }
    ]
  }'
```

```json
{ "accepted": 3, "rejected": [] }
```

- `userId` (string, required): Your id of the user, 1 to 128 characters.
- `isrc` (string, required): The track. An ISRC that MusicAPI does not know is accepted and stored: a later model can know it.
- `type` (string, required): `play`, `complete`, `like`, `skip` or `dislike`.
- `at` (string (ISO 8601), required): When it happened.
- `msPlayed` (integer): 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:

| `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

```bash
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](https://musicapi.com/docs/recommendations/recommendation-catalogues.md) 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.

```bash
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): 1 to 50.
- `maxPerArtist` (integer): 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)

```bash
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](https://musicapi.com/docs/recommendations/recommendations.md#billing).
