Find Similar

GET

https://api.audioscape.ai/developer/v1/similar

On this pageEndpoint

▼

Endpoint
Headers
Query Parameters
Response
Example
Errors

Endpoint

Given a track's asset ID, find other tracks that sound similar. Great for building "more like this" features or curating playlists based on a seed track.

Headers

Name	Type	Description
x-api-key	required	Your API key

Query Parameters

Parameter	Type	Description
asset_id	string required	The Roblox asset ID of the track to find similar music for
limit	number optional	Maximum results to return (default: 20, max: 100)
offset	number optional	Pagination offset (default: 0)
filters	object optional	JSON-encode the object and pass as a single querystring value (e.g. `filters={"genres":["electronic"]}`). Narrow your results: `genres`—Array of canonical genre values (e.g. `"Electronic"`) or URL-safe slugs (e.g. `"electronic"`). Legacy Roblox `music_genre` slugs are also accepted and resolve to the canonical taxonomy. `duration`—Object with `min` and `max` in seconds
max_score	number optional	Drops results whose `score` is at or above this threshold (between `0` and `1`). Useful for filtering out near-duplicates of the seed track. Omit to return all results.
dedupe	boolean optional	Shortcut for filtering near-duplicates without picking a number — equivalent to a sensible default `max_score`. If both are set, `max_score` wins.

Response

Returns tracks that are acoustically similar to the given track.

Each track also carries additive optional MIR (music information retrieval) fields. They may be null when a track hasn't been analyzed, so always null-check. Note: loudness_lufs can be non-finite (Inf/NaN) — filter those out before ranking or averaging; danceability is long-tailed, so rank by percentile rather than an absolute cutoff; and genres_detailed scores are small — use their relative rank.

response.json

{
  "tracks": [
    {
      "asset_id": "string",
      "name": "string",
      "artist": "string",
      "album": "string",
      "duration": number,
      "genre": "string",        // canonical, e.g. "Hip Hop / Rap"
      "genre_slug": "string",   // URL-safe, e.g. "hip-hop-rap" — pass to /v1/browse?type=genre&name=
      "bpm": number,
      "score": number,

      // --- MIR fields (all optional, may be null) ---
      "loudness_lufs": number,   // integrated EBU R128 loudness; filter out Inf/NaN before ranking/averaging
      "true_peak_dbtp": number,  // true peak in dBTP; > 0 means over / clipping
      "mood": {                  // each ~0..1 except arousal (−1..1); use arousal for relative energy
        "arousal": number,
        "happy": number,
        "sad": number,
        "aggressive": number,
        "relaxed": number,
        "party": number,
        "danceable": number
      },
      "key": "string",           // e.g. "C", "Eb"
      "scale": "string",         // "major" | "minor"
      "key_confidence": number,  // 0..1
      "voice": "string",         // "voice" | "instrumental"
      "voice_confidence": number,// 0..1
      "electronic": "string",    // character label
      "acoustic": "string",      // character label
      "timbre": "string",        // character label
      "danceability": number,    // long-tailed — rank by percentile, not an absolute threshold
      "genres_detailed": [       // top-5 Discogs predictions; use relative rank (scores are small)
        { "label": "string", "parent": "string", "score": number }  // parent may be absent
      ]
    }
  ],
  "meta": {
    "total": number,
    "limit": number,
    "offset": number
  }
}

Example Request

Radio mode: when one track finishes, queue another that sounds like it so the vibe carries. Assumes a client from the Quickstart.

Luau (Roblox)

-- Radio mode: when the current track ends, queue one that sounds like it
-- Note: bgmSound.Looped must be false, otherwise Ended never fires
local nowPlayingId = "123456789"

bgmSound.Ended:Connect(function()
    local result, err = client:similar({
        asset_id = nowPlayingId,
        limit = 1,
    })
    if not result or #result.tracks == 0 then
        warn(err or "no similar tracks")
        return
    end

    nowPlayingId = result.tracks[1].asset_id
    bgmSound.SoundId = "rbxassetid://" .. nowPlayingId
    bgmSound:Play()
end)

Error Responses

400Bad Request

Missing or invalid asset ID.

400.json

{
  "error": "Missing required field: asset_id"
}

401Unauthorized

Invalid or missing API key.

401.json

{
  "error": "Invalid API key"
}

429Too Many Requests

You've exceeded your rate limit. See your current tier on the API Keys page.

429.json

{
  "message": "Too Many Requests"
}

500Internal Server Error

Something went wrong on our end. Try again or contact support if the issue persists.

Ready to get started?

Create your API key and start building with AudioScape today.

Get Your API Key