Find similar tracks
GET/v1/tracks/{id}/similar
Get precomputed same-kind neighbors, closest first. An empty list is possible. Post-filters run before paging and total.
Needs an API key. Send it in the Authorization: Bearer header.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id required | Path | string | The track id, such as fp-0000000001, from a search result. |
limit optional | Query | string | Number of tracks per page, from 1 to 50. Default: 20. Pattern: ^\d+$ |
cursor optional | Query | string | The cursor from the previous response, to get the next page. Pattern: ^\d{1,9}$ |
min_bpm optional | Query | string | Pattern: ^\d+(\.\d+)?$ |
max_bpm optional | Query | string | Pattern: ^\d+(\.\d+)?$ |
min_seconds optional | Query | string | Pattern: ^\d+(\.\d+)?$ |
max_seconds optional | Query | string | Pattern: ^\d+(\.\d+)?$ |
commercial optional | Query | string | true keeps tracks the license lets you use commercially ("Free for commercial use" on the site). false keeps only non-commercial tracks. Default: both. One of: true, false |
Show all 10 parameters
| Name | In | Type | Description |
|---|---|---|---|
credit optional | Query | string | One of: optional, requested |
loops_only optional | Query | string | One of: true, false |
Responses
200OK.object · Content: application/json
Name Type Description tracksrequiredarray of Track totalrequirednumber How many precomputed neighbors remain after post-filters. cursorrequiredstring or null Pass as cursor to get the next page. null on the last page. 400A parameter is not valid, or does not apply to the requested kind. The message names it.Schema Error · Content: application/json
Error fields (8)
Name Type Description errorrequiredstring A short code: missing_api_key, invalid_api_key, invalid_parameter, invalid_filter_for_kind, not_found, rate_limited, method_not_allowed, or internal_error. messagerequiredstring What went wrong, in plain words. parameteroptionalstring On invalid_parameter and invalid_filter_for_kind, the invalid parameter or field. invalid_valuesoptionalarray of string Unknown controlled filter ids. discoveryoptionalstring The endpoint listing valid filter ids and labels. limitoptionalstring Only on rate_limited: which limit you hit. One of: minute, day, month retry_afteroptionalnumber Only on rate_limited: seconds to wait before retrying. reset_atoptionalstring Only on rate_limited: when that limit resets, as an ISO 8601 UTC time. 401The API key is missing, not valid, or revoked.Schema Error · Content: application/json
Error fields (8)
Name Type Description errorrequiredstring A short code: missing_api_key, invalid_api_key, invalid_parameter, invalid_filter_for_kind, not_found, rate_limited, method_not_allowed, or internal_error. messagerequiredstring What went wrong, in plain words. parameteroptionalstring On invalid_parameter and invalid_filter_for_kind, the invalid parameter or field. invalid_valuesoptionalarray of string Unknown controlled filter ids. discoveryoptionalstring The endpoint listing valid filter ids and labels. limitoptionalstring Only on rate_limited: which limit you hit. One of: minute, day, month retry_afteroptionalnumber Only on rate_limited: seconds to wait before retrying. reset_atoptionalstring Only on rate_limited: when that limit resets, as an ISO 8601 UTC time. 404No track has that id.Schema Error · Content: application/json
Error fields (8)
Name Type Description errorrequiredstring A short code: missing_api_key, invalid_api_key, invalid_parameter, invalid_filter_for_kind, not_found, rate_limited, method_not_allowed, or internal_error. messagerequiredstring What went wrong, in plain words. parameteroptionalstring On invalid_parameter and invalid_filter_for_kind, the invalid parameter or field. invalid_valuesoptionalarray of string Unknown controlled filter ids. discoveryoptionalstring The endpoint listing valid filter ids and labels. limitoptionalstring Only on rate_limited: which limit you hit. One of: minute, day, month retry_afteroptionalnumber Only on rate_limited: seconds to wait before retrying. reset_atoptionalstring Only on rate_limited: when that limit resets, as an ISO 8601 UTC time. 429Over your plan's limit. Free accounts get 20 calls per minute and 300 calls per day. Pro accounts get 60 calls per minute and 20,000 calls per month (UTC). MCP and the API share one allowance per account. The Retry-After header gives the seconds to wait, up to 86,400, and the limit and reset_at fields in the body name the limit you hit and when it resets.Schema Error · Content: application/json
Error fields (8)
Name Type Description errorrequiredstring A short code: missing_api_key, invalid_api_key, invalid_parameter, invalid_filter_for_kind, not_found, rate_limited, method_not_allowed, or internal_error. messagerequiredstring What went wrong, in plain words. parameteroptionalstring On invalid_parameter and invalid_filter_for_kind, the invalid parameter or field. invalid_valuesoptionalarray of string Unknown controlled filter ids. discoveryoptionalstring The endpoint listing valid filter ids and labels. limitoptionalstring Only on rate_limited: which limit you hit. One of: minute, day, month retry_afteroptionalnumber Only on rate_limited: seconds to wait before retrying. reset_atoptionalstring Only on rate_limited: when that limit resets, as an ISO 8601 UTC time.
{
"tracks": [
{
"id": "example",
"title": "example",
"artist": "example",
"description": "example",
"kind": "music",
"duration_s": 1,
"bpm": 1,
"tags": {
"genre": [],
"mood": [],
"use": [],
"instrument": [],
"sfx": []
},
"category": {
"id": "example",
"label": "example",
"top_id": "example",
"top_label": "example"
},
"license": {
"id": "cc0",
"name": "example",
"url": "example",
"status": "verified"
},
"terms": {
"commercial": true,
"credit": "none",
"share_alike": true
},
"attribution": "optional",
"credit_line": "example",
"original_url": "example",
"source_page": "example",
"preview_url": "example",
"page_url": "example",
"untrusted_fields": [
"example"
],
"timing": {
"onset_ms": 1,
"peak_ms": 1,
"tail_ms": 1
},
"loudness": {
"integrated_lufs": 1,
"true_peak_db": 1
}
}
],
"total": 1,
"cursor": "example"
} Copy only. No request is sent from this page, so your key never goes into a web page. The samples read it from the UNCOMMON_EAR_API_KEY environment variable.