API reference / Catalog

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.

Get a key

Parameters

NameInTypeDescription
id requiredPathstringThe track id, such as fp-0000000001, from a search result.
limit optionalQuerystringNumber of tracks per page, from 1 to 50. Default: 20. Pattern: ^\d+$
cursor optionalQuerystringThe cursor from the previous response, to get the next page. Pattern: ^\d{1,9}$
min_bpm optionalQuerystring Pattern: ^\d+(\.\d+)?$
max_bpm optionalQuerystring Pattern: ^\d+(\.\d+)?$
min_seconds optionalQuerystring Pattern: ^\d+(\.\d+)?$
max_seconds optionalQuerystring Pattern: ^\d+(\.\d+)?$
commercial optionalQuerystringtrue 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
NameInTypeDescription
credit optionalQuerystring One of: optional, requested
loops_only optionalQuerystring One of: true, false

Responses

  • 200 OK.

    object · Content: application/json

    NameTypeDescription
    tracks requiredarray of Track
    total requirednumberHow many precomputed neighbors remain after post-filters.
    cursor requiredstring or nullPass as cursor to get the next page. null on the last page.
  • 400 A parameter is not valid, or does not apply to the requested kind. The message names it.

    Schema Error · Content: application/json

    Error fields (8)
    NameTypeDescription
    error requiredstringA short code: missing_api_key, invalid_api_key, invalid_parameter, invalid_filter_for_kind, not_found, rate_limited, method_not_allowed, or internal_error.
    message requiredstringWhat went wrong, in plain words.
    parameter optionalstringOn invalid_parameter and invalid_filter_for_kind, the invalid parameter or field.
    invalid_values optionalarray of stringUnknown controlled filter ids.
    discovery optionalstringThe endpoint listing valid filter ids and labels.
    limit optionalstringOnly on rate_limited: which limit you hit. One of: minute, day, month
    retry_after optionalnumberOnly on rate_limited: seconds to wait before retrying.
    reset_at optionalstringOnly on rate_limited: when that limit resets, as an ISO 8601 UTC time.
  • 401 The API key is missing, not valid, or revoked.

    Schema Error · Content: application/json

    Error fields (8)
    NameTypeDescription
    error requiredstringA short code: missing_api_key, invalid_api_key, invalid_parameter, invalid_filter_for_kind, not_found, rate_limited, method_not_allowed, or internal_error.
    message requiredstringWhat went wrong, in plain words.
    parameter optionalstringOn invalid_parameter and invalid_filter_for_kind, the invalid parameter or field.
    invalid_values optionalarray of stringUnknown controlled filter ids.
    discovery optionalstringThe endpoint listing valid filter ids and labels.
    limit optionalstringOnly on rate_limited: which limit you hit. One of: minute, day, month
    retry_after optionalnumberOnly on rate_limited: seconds to wait before retrying.
    reset_at optionalstringOnly on rate_limited: when that limit resets, as an ISO 8601 UTC time.
  • 404 No track has that id.

    Schema Error · Content: application/json

    Error fields (8)
    NameTypeDescription
    error requiredstringA short code: missing_api_key, invalid_api_key, invalid_parameter, invalid_filter_for_kind, not_found, rate_limited, method_not_allowed, or internal_error.
    message requiredstringWhat went wrong, in plain words.
    parameter optionalstringOn invalid_parameter and invalid_filter_for_kind, the invalid parameter or field.
    invalid_values optionalarray of stringUnknown controlled filter ids.
    discovery optionalstringThe endpoint listing valid filter ids and labels.
    limit optionalstringOnly on rate_limited: which limit you hit. One of: minute, day, month
    retry_after optionalnumberOnly on rate_limited: seconds to wait before retrying.
    reset_at optionalstringOnly on rate_limited: when that limit resets, as an ISO 8601 UTC time.
  • 429 Over 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)
    NameTypeDescription
    error requiredstringA short code: missing_api_key, invalid_api_key, invalid_parameter, invalid_filter_for_kind, not_found, rate_limited, method_not_allowed, or internal_error.
    message requiredstringWhat went wrong, in plain words.
    parameter optionalstringOn invalid_parameter and invalid_filter_for_kind, the invalid parameter or field.
    invalid_values optionalarray of stringUnknown controlled filter ids.
    discovery optionalstringThe endpoint listing valid filter ids and labels.
    limit optionalstringOnly on rate_limited: which limit you hit. One of: minute, day, month
    retry_after optionalnumberOnly on rate_limited: seconds to wait before retrying.
    reset_at optionalstringOnly on rate_limited: when that limit resets, as an ISO 8601 UTC time.
Request: GET /v1/tracks/{id}/similar
curl · Request, GET /v1/tracks/{id}/similar
curl "https://api.uncommonear.com/v1/tracks/fp-0000000001/similar?limit=example&cursor=example&min_bpm=example" \
  -H "Authorization: Bearer $UNCOMMON_EAR_API_KEY"
JavaScript · Request, GET /v1/tracks/{id}/similar
const url = "https://api.uncommonear.com/v1/tracks/fp-0000000001/similar?" + new URLSearchParams({ limit: "example", cursor: "example", min_bpm: "example" });
const response = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.UNCOMMON_EAR_API_KEY}` },
});
const data = await response.json();
console.log(response.status, data);
Python · Request, GET /v1/tracks/{id}/similar
import os
import requests

response = requests.get(
    "https://api.uncommonear.com/v1/tracks/fp-0000000001/similar",
    params={"limit": "example", "cursor": "example", "min_bpm": "example"},
    headers={"Authorization": "Bearer " + os.environ["UNCOMMON_EAR_API_KEY"]},
)
print(response.status_code, response.json())
JSON · 200 response
{
  "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.