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

`GET https://api.musicapi.com/public/recommendations/similar-tracks`

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.

Finds tracks that listeners put next to the seed track, from playlist co-occurrence across music services. No audio is analysed. The seed itself is never in the answer. `basis` says what the answer is built on: `track` (the track's own vector) or `artist` (the track has no vector yet, so its artist's vector is used). With `catalogue`, every result is in that catalogue. Answers are cached for a model version. Each call counts as one recommendation request on your usage.

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `isrc` | string | yes | The seed track's ISRC: 12 characters. Dashes, spaces and lower case are accepted. Any ISRC of the track works. |
| `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. |
| `limit` | number | no | How many results to return. Default: `20`. |
| `maxPerArtist` | number | no | At most this many tracks of one artist. Default: `2`. |
| `excludeSameArtist` | boolean | no | Leave out every track of the seed's artist. Default: `false`. |

## Response 200

ok

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `modelVersion` | string | yes | The model version that made the answer. |
| `basis` | string | yes | What the answer is built on: the track's own vector, or its artist's vector. One of: track, artist, genre. |
| `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",
  "basis": "track",
  "tracks": [
    {
      "isrc": "USRC17607839",
      "score": 0.8731,
      "title": "Forests",
      "artist": {
        "id": "123456",
        "name": "LaziiBee"
      }
    }
  ]
}
```

## Errors

- 400: The ISRC is not a 12-character ISRC, or a parameter is out of range.
- 401: No valid credential.
- 404: `no_signal`: the seed ISRC has no vector and its artist has none either. `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/similar-tracks \
  -u "$MUSICAPI_CLIENT_ID:$MUSICAPI_CLIENT_SECRET"
```
