Browse

POST

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

On this pageEndpoint

▼

Endpoint
Headers
Request Body
Browse Types
List Response
Tracks Response
Example
Errors

Endpoint

Browse the AudioScape catalog by artist, album, genre, mood, or trending. Use this endpoint to list available entities, drill into a specific one to get its tracks, or fetch the popularity-ranked trending list.

Headers

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

Request Body

Parameter	Type	Description
type	string required	One of: `artist`, `album`, `genre`, `mood`, `trending`
name	string optional	Name of the entity to browse. When provided, returns tracks belonging to that entity. When omitted, lists all entities of the given type.
limit	number optional	Maximum results to return (default: 20, max: 100)
offset	number optional	Pagination offset (default: 0)

Browse Types

artist

Lists artists with track and album counts. Drill into an artist to get all their tracks.

album

Lists albums with artist and track count. Drill into an album to get its tracks.

genre

Lists all available genres with track counts. Use the genre name to get all tracks in that genre.

mood

Lists available moods (Happy, Exciting, Ambient, etc.) with track counts. Browse tracks by mood to curate playlists.

trending

Popularity-ranked tracks across the catalog, refreshed daily. No name required — the response is always a tracks list. Engagement signals (plays, favorites, votes, queue adds, listen duration, plus high-value SDK custom events) are exponentially decayed over a 60-day window so recent activity dominates.

List Response

When name is omitted, returns a list of entities. The shape of each item depends on the type:

Artist / Album List

{
  "items": [
    {
      "name": "string",
      "track_count": number,
      "album_count": number    // artist only
      "artist": "string",     // album only
      "genre": "string"       // album only
    }
  ],
  "meta": {
    "total": number,
    "limit": number,
    "offset": number,
    "type": "artist" | "album"
  }
}

Genre / Mood List

{
  "items": [
    {
      "name": "string",
      "display_name": "string",
      "track_count": number
    }
  ],
  "meta": {
    "total": number,
    "limit": number,
    "offset": number,
    "type": "genre" | "mood"
  }
}

Tracks Response

When name is provided, returns tracks belonging to that entity. Same track format as the search endpoint.

tracks.json

{
  "tracks": [
    {
      "asset_id": "string",
      "name": "string",
      "artist": "string",
      "album": "string",
      "duration": number,
      "genre": "string",
      "bpm": number,
      "score": number
    }
  ],
  "meta": {
    "total": number,
    "limit": number,
    "offset": number,
    "type": "artist" | "album" | "genre" | "mood" | "trending",
    "name": "string"        // omitted for trending
  }
}

Example Requests

Power a lobby jukebox or in-game music room: list the genres to populate a picker, then fetch tracks for whichever one the player taps. Assumes a client from the Quickstart.

Luau (Roblox)

-- Lobby jukebox: populate a genre picker, fetch tracks on click
local genres, err = client:browse({ type = "genre" })
if not genres then warn(err) return end

for _, genre in genres.items do
    local button = Instance.new("TextButton")
    button.Text = `{genre.display_name} ({genre.track_count})`
    button.Size = UDim2.fromOffset(200, 32)
    button.Parent = genreList -- your Frame holding the genre buttons

    button.Activated:Connect(function()
        local tracks, trackErr = client:browse({
            type = "genre",
            name = genre.name,
            limit = 25,
        })
        if not tracks then warn(trackErr) return end

        print("Loaded", #tracks.tracks, "tracks for", genre.display_name)
    end)
end

Error Responses

400Bad Request

Missing or invalid type parameter.

400.json

{
  "error": "type is required and must be one of: artist, album, genre, mood, trending"
}

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