GET
TracksRecommendations
Return recommended tracks based on one or more seed artists and/or genres. Pass either artist_ids, genres, or both.
/v1/recommendationsMethod
GET
Path
/v1/recommendations
Group
Tracks
At least one of artist_ids or genres is required. Multiple values are passed as comma-separated lists.
Overview
How to use this endpoint
Use this endpoint when you need structured API data in a predictable JSON shape. Reference the request example, required parameters, and response fields below to wire it into your product or internal tool.
Response format
JSON response
All successful responses return data in a stable JSON envelope and use Tune UUIDs for resource identifiers.
Code example
Example request
request
Copy-ready
GET /v1/recommendations?artist_ids=a87ff679-a2f3-71d1-9ad8-0800200c9a66&genres=electronic,ambient&limit=20Request parameters
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
artist_ids | string | No | Comma-separated list of artist Tune IDs to seed recommendations from. |
genres | string | No | Comma-separated list of genre slugs such as electronic, ambient, or indie-pop. |
limit | integer | No | Number of records to return. Default 20, maximum 100. |
cursor | string | No | Opaque cursor returned by a previous paginated response. |
Response schema
Response fields
| Field | Type | Description |
|---|---|---|
tune_id | uuid | Unique Tune track identifier. |
name | string | Track title. |
duration_ms | integer | Track duration in milliseconds. |
track_number | integer | Position on the release. |
disc_number | integer | Disc number on multi-disc releases. |
explicit | boolean | Whether the track is explicit. |
isrc | string | null | International recording code. |
popularity | integer | Relative popularity score from 0 to 100. |
preview_url | string | null | Short preview audio URL if available. |
available_markets | string[] | Country codes where the track is available. |
album | object | Album summary with tune_id, name, and release_date. |
artists | object[] | Artist summaries with tune_id and name. |
images | object[] | Artwork images with url, width, and height. |
Code example
Example response
application/json
Copy-ready
{
"data": [
{
"tune_id": "b3f6e4a0-4cf0-4c17-9eb1-b7456005d111",
"name": "Midnight Runner",
"duration_ms": 226420,
"track_number": 6,
"disc_number": 1,
"explicit": false,
"isrc": "QZDAA2331187",
"popularity": 69,
"preview_url": "https://cdn.tune.dev/previews/b3f6e4a0.mp3",
"available_markets": ["US", "GB"],
"album": {
"tune_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Signal Loss",
"release_date": "2023-06-14"
},
"artists": [
{
"tune_id": "a87ff679-a2f3-71d1-9ad8-0800200c9a66",
"name": "Nova Circuit"
}
],
"images": [
{
"url": "https://cdn.tune.dev/images/7c9e6679_300.jpg",
"width": 300,
"height": 300
}
]
}
],
"pagination": {
"limit": 20,
"next_cursor": "eyJvZmZzZXQiOjIwfQ=="
}
}Next steps