# Recommend tracks for a listener
URL: https://musicapi.com/docs/reference/recommendations-for-user.md

`GET https://api.musicapi.com/public/recommendations/users/{userId}/recommendations`

Section: Recommendations.
Product: MusicAPI Core.
Auth: Basic (any one of them). Use Basic with your Client ID and Client Secret from your server only.

Tracks for one listener, from the events you sent for them. Recent events count more (half-life 30 days); a like counts most, a dislike pushes away. Tracks the listener already has in their last 500 events are left out. A listener without usable events answers 404 `no_signal`. Each answered call counts the listener as a personalised user of the month. Needs Client Secret authentication.

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `userId` | string | yes | Your own id of the listener, 1 to 128 characters. We store it only under your account. |

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | number | no | How many tracks to return. Default: `20`. |
| `catalogue` | string | no | The id of one of your catalogues. Results then come only from that catalogue. Leave it out for the whole MusicAPI catalogue. |
| `maxPerArtist` | number | no | At most this many tracks of one artist. Default: `2`. |

## Response 200

ok

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `modelVersion` | string | yes |  |
| `tracks` | RecommendationTrack[] | yes |  |
| `tracks[].isrc` | string | yes | With `catalogue`: your own ISRC of the track. Else one ISRC of the track. |
| `tracks[].score` | number | yes | The similarity to the seeds, up to 1. |
| `tracks[].title` | string \| null | yes | A display aid. Your own metadata stays the source of truth. |
| `tracks[].artist` | object | yes |  |
| `tracks[].artist.id` | string | yes | The MusicAPI artist id. Use it as an artist seed. |
| `tracks[].artist.name` | string \| null | yes |  |

```json
{
  "modelVersion": "2026-11-13",
  "tracks": [
    {
      "isrc": "USRC17607839",
      "score": 0.8731,
      "title": "Forests",
      "artist": {
        "id": "123456",
        "name": "LaziiBee"
      }
    }
  ]
}
```

## Errors

- 400: A parameter is out of range.
- 401: No valid credential.
- 403: The request does not use Client Secret authentication.
- 404: `no_signal`: no usable events for this listener. `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.

## Example

```bash
curl https://api.musicapi.com/public/recommendations/users/{userId}/recommendations \
  -u "$MUSICAPI_CLIENT_ID:$MUSICAPI_CLIENT_SECRET"
```
