# Recommend the next tracks
URL: https://musicapi.com/docs/reference/recommendations-next.md

`POST https://api.musicapi.com/public/recommendations/next`

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

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.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `userId` | string | no | Your own id of the listener. Optional. |
| `recent` | string[] | no | The ISRCs just played, newest first. |
| `skipped` | string[] | no | ISRCs the listener skipped in this session. |
| `exclude` | string[] | no | ISRCs to leave out. |
| `limit` | number | no |  |
| `catalogue` | string | no | The id of one of your catalogues. |
| `maxPerArtist` | number | no |  |

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

## Example

```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":"string","recent":["string"],"skipped":["string"],"exclude":["string"],"limit":20,"catalogue":"42","maxPerArtist":2}'
```
