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	What you're looking for — an artist name, mood, genre, or description
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 Roblox music genre slugs (e.g. `"electronic"`, `"pop"`) `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`

Response

Returns matching tracks along with grouped artist and album information.

response.json

{
  "tracks": [
    {
      "asset_id": "string",
      "name": "string",
      "artist": "string",
      "album": "string",
      "duration": number,
      "genre": "string",
      "bpm": number,
      "score": number
    }
  ],
  "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",
    "matched_artist": "string" | null
  }
}

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.

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