Browse

GET

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

On this pageEndpoint

▼

Endpoint
Headers
Query Parameters
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

Query Parameters

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)
sort	string optional	Order tracks within a drill-down. One of `popular` (default — global popularity ranking, same signals as `trending`), `alpha` (track name A→Z), `recent` (newest first by upload date). Ignored for list mode and for `trending` (already popularity-ordered). Tracks with no engagement data are omitted under `popular`; use `alpha` or `recent` to include them.

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 genres with track counts. Each item exposes a URL-safe slug (e.g. hip-hop-rap) alongside the canonical name. Drill in by passing either the slug or the canonical as name.

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",
      "slug": "string",          // genre only — URL-safe id, pass back as name=
      "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",        // canonical, e.g. "Hip Hop / Rap"
      "genre_slug": "string",   // URL-safe, e.g. "hip-hop-rap"
      "bpm": number,
      "score": number           // popularity score when sort="popular"
    }
  ],
  "meta": {
    "total": number,
    "limit": number,
    "offset": number,
    "type": "artist" | "album" | "genre" | "mood" | "trending",
    "name": "string",        // omitted for trending
    "sort": "popular" | "alpha" | "recent"
  }
}

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()
        -- name accepts the slug (URL-safe, e.g. "hip-hop-rap") or the
        -- canonical (e.g. "Hip Hop / Rap"). Slug is preferred for URL
        -- transport; both resolve to the same tracks.
        local tracks, trackErr = client:browse({
            type = "genre",
            name = genre.slug,
            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