Search Music

POST

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

On this pageEndpoint

▼

Endpoint
Headers
Request Body
Response
Search Features
Example
Try It
Errors

Endpoint

Search our catalog of music using natural language. Describe a mood, genre, or style and the API returns the most relevant tracks. Artist-based queries are also supported.

Headers

Name	Type	Description
x-api-key	required	Your API key
Content-Type	required	Must be `application/json`

Request Body

Parameter	Type	Description
query	string required (or asset_ids)	What you're looking for — an artist name, mood, genre, or description. Special shapes: a single numeric string is treated as an asset ID lookup; a comma-delimited list of numeric IDs (e.g. `"123,456,789"`) is treated as a batch lookup. See Asset ID lookup below.
asset_ids	string[] optional	Explicit batch ID lookup. Array of numeric strings, max 100 per call. When present, takes priority over `query` and bypasses all `filters`. Returns matching tracks in input order; IDs that don't exist (or are deleted/delisted/non-public) appear in`meta.missing_ids`.
limit	number optional	Maximum results to return (default: 20, max: 100)
offset	number optional	Pagination offset (default: 0)
filters	object optional	Narrow your results: `genres`—Array of canonical genre values (e.g. `"Hip Hop / Rap"`) or URL-safe slugs (e.g. `"hip-hop-rap"`, `"pop"`). Legacy Roblox `music_genre` slugs are also accepted and resolve to the canonical taxonomy. `duration`—Object with `min` and `max` in seconds `min_play_count`—Minimum lifetime play count on Roblox (number) `min_likes`—Minimum lifetime like count on Roblox (number) `created_after`—Earliest asset creation date — `YYYY-MM-DD` `instrumental`—Boolean. `true` returns only instrumental tracks (no vocals). Omit to include all tracks. `electronic`—Boolean. `true` returns only tracks classified electronic. Omit to include all tracks. `acoustic`—Boolean. `true` returns only tracks classified acoustic. Omit to include all tracks. `key`—Musical key — one of `C, C#, D, Eb, E, F, F#, G, Ab, A, Bb, B`. `scale`—`"major"` or `"minor"`. `gender`—`"male"` or `"female"`. Only meaningful on vocal tracks — the API gates this filter on voice, so instrumental tracks are excluded.

Response

Returns matching tracks along with grouped artist and album information.

Each track also carries additive optional MIR (music information retrieval) fields. They may be null when we haven't analyzed a track yet, so always null-check before using them. A few caveats worth honoring: 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, not raw magnitude.

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
      ]
    }
  ],
  "artists": [
    {
      "name": "string",
      "track_count": number
    }
  ],
  "albums": [
    {
      "name": "string",
      "artist": "string",
      "track_count": number
    }
  ],
  "meta": {
    "total": number,
    "limit": number,
    "offset": number,
    "search_method": "semantic" | "text" | "id" | "ids-batch",
    "matched_artist": "string" | null,
    "missing_ids": ["string"]   // ID-lookup mode only, omitted when empty
  }
}

Search Features

Natural Language

Default

Describe what you're looking for in plain language — "upbeat summer vibes", "dark cinematic tension", or "chill lo-fi beats" — and get semantically relevant results.

Smart Substitution

When you search for content that isn't available on the platform — like a specific artist or song — AudioScape automatically resolves the query with music in the same sound and style from our catalog. The meta.matched_artist field tells you which artist was matched.

Keyword Fallback

If semantic search is unavailable, the API automatically falls back to keyword matching so you always get results. Check meta.search_method to see which method was used.

Asset ID Lookup

When you already know the asset IDs (e.g. rendering a recently-played list, rebuilding a playlist UI, refreshing track metadata), short-circuit the scoring pipeline with a direct lookup. Three input shapes work:

Single ID via query: "12345" — returns the track if found, otherwise falls through to text search
Comma-delimited list via query: "123,456,789" — batch lookup
Explicit array via asset_ids: ["123","456"] — batch lookup, no fall-through

Up to 100 IDs per call. Filters don't apply (an explicit ID lookup means you want THAT track, not a narrowing). Returned tracks preserve input order. Missing IDs (deleted, delisted, non-public, never existed) are listed in meta.missing_ids. meta.search_method is "id" for single, "ids-batch" for multi.

Example Request

Mood-driven music: when the player enters a tagged zone, search for a fitting track and swap the background music. Assumes a client from the Quickstart.

Luau (Roblox)

-- Swap BGM when the player enters the boss arena
local result, err = client:search({
    query = "dark cinematic boss tension",
    limit = 1,
})
if not result or #result.tracks == 0 then
    warn(err or "no tracks")
    return
end

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

Try It

Test the API with your own key. Responses hit the live endpoint.

Response will appear here

Error Responses

400Bad Request

Missing or invalid parameters.

400.json

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

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