getTrack

getTrack(params, requestInit?)

Get a track by id.

Example:

const { data: track } = await audiusSdk.tracks.getTrack({
  trackId: 'D7KyD',
})
 
console.log(track)

Params

Create an object with the following fields and pass it as the first argument, as shown in the example above.

You can pass an optional RequestInit object as the second argument to customize the underlying fetch request (e.g. set custom headers, abort signal, etc.).

Returns

Returns a Promise containing an object with a data field. data contains a TrackResponse object.

getBulkTracks

getBulkTracks(params, requestInit?)

Get a list of tracks using their IDs or permalinks.

Example:

const { data: tracks } = await audiusSdk.tracks.getBulkTracks({
  id: ['D7KyD', 'PjdWN', 'Jwo2A'],
})
console.log(tracks)

Params

Create an object with the following fields and pass it as the first argument, as shown in the example above.

You can pass an optional RequestInit object as the second argument to customize the underlying fetch request (e.g. set custom headers, abort signal, etc.).

Returns

Returns a Promise containing an object with a data field. data is an array of TrackResponse objects.

getTrendingTracks

getTrendingTracks(params, requestInit?)

Get the top 100 trending (most popular) tracks on Audius.

Example:

const { data: tracks } = await audiusSdk.tracks.getTrendingTracks()
console.log(tracks)

Params

Optionally create an object with the following fields and pass it as the first argument, as shown in the example above.

You can pass an optional RequestInit object as the second argument to customize the underlying fetch request (e.g. set custom headers, abort signal, etc.).

Returns

Returns a Promise containing an object with a data field. data is an array of TrackResponse objects.

getUndergroundTrendingTracks

getUndergroundTrendingTracks(params, requestInit?)

Get the top 100 trending underground tracks on Audius.

Example:

const { data: tracks } = await audiusSdk.tracks.getUndergroundTrendingTracks()
console.log(tracks)

Params

Optionally create an object with the following fields and pass it as the first argument, as shown in the example above.

You can pass an optional RequestInit object as the second argument to customize the underlying fetch request (e.g. set custom headers, abort signal, etc.).

Returns

Returns a Promise containing an object with a data field. data is an array of TrackResponse objects.

searchTracks

searchTracks(params, requestInit?)

Search for tracks.

Example:

const { data: tracks } = await audiusSdk.tracks.searchTracks({
  query: 'skrillex',
})
console.log(tracks)

Params

Create an object with the following fields and pass it as the first argument, as shown in the example above.

You can pass an optional RequestInit object as the second argument to customize the underlying fetch request (e.g. set custom headers, abort signal, etc.).

Returns

Returns a Promise containing an object with a data field. data is an array of TrackResponse objects.

createTrack

createTrack(params, requestInit?)

Create a track by registering its metadata on the protocol. This method accepts metadata including CIDs (Content Identifiers) that reference previously uploaded files — it does not accept raw audio or image files directly.

Example:

import fs from 'fs'
 
// First, upload files using the Uploads API
const trackBuffer = fs.readFileSync('path/to/track.mp3')
const audioUpload = audiusSdk.uploads.createAudioUpload({
  file: {
    buffer: Buffer.from(trackBuffer),
    name: 'track.mp3',
    type: 'audio/mpeg',
  },
})
const audioResult = await audioUpload.start()
 
const coverArtBuffer = fs.readFileSync('path/to/cover-art.png')
const imageUpload = audiusSdk.uploads.createImageUpload({
  file: {
    buffer: Buffer.from(coverArtBuffer),
    name: 'cover-art.png',
    type: 'image/png',
  },
})
const coverArtCid = await imageUpload.start()
 
// Then, create the track with the returned CIDs.
// The audio upload result fields (trackCid, origFileCid, etc.) match
// the metadata field names, so you can spread them directly.
const { data } = await audiusSdk.tracks.createTrack({
  userId: '7eP5n',
  metadata: {
    title: 'Monstera',
    description: 'Dedicated to my favorite plant',
    genre: 'Metal',
    mood: 'Aggressive',
    ...audioResult,
    coverArtSizes: coverArtCid,
  },
})

Params

Create an object with the following fields and pass it as the first argument, as shown in the example above.

See CreateTrackRequestBody for all available metadata fields.

You can pass an optional RequestInit object as the second argument to customize the underlying fetch request (e.g. set custom headers, abort signal, etc.).

Returns

Returns a Promise resolving to an object with the following fields:

{
  transactionHash?: string
  trackId?: string
}
 
---
 
## updateTrack
 
> #### updateTrack(`params`, `requestInit?`)
 
Update a track's metadata. If any metadata fields are not provided, their values will be kept the
same as before. To replace audio or cover art, upload new files via the
[Uploads API](/sdk/uploads) and pass the new CIDs in `metadata`.
 
Example:
 
```ts
const { data } = await audiusSdk.tracks.updateTrack({
  trackId: 'h5pJ3Bz',
  userId: '7eP5n',
  metadata: {
    description: 'Dedicated to my favorite plant... updated!',
    mood: 'Yearning',
  },
})

Params

Create an object with the following fields and pass it as the first argument, as shown in the example above.

All fields are optional — only include the fields you want to change. See UpdateTrackRequestBody for all available fields.

You can pass an optional RequestInit object as the second argument to customize the underlying fetch request (e.g. set custom headers, abort signal, etc.).

Returns

Returns a Promise resolving to an object with the following fields:

{
  transactionHash?: string
}

deleteTrack

deleteTrack(params, requestInit?)

Delete a track

Example:

await audiusSdk.tracks.deleteTrack({
  trackId: 'h5pJ3Bz',
  userId: '7eP5n',
})

Params

Create an object with the following fields and pass it as the first argument, as shown in the example above.

You can pass an optional RequestInit object as the second argument to customize the underlying fetch request (e.g. set custom headers, abort signal, etc.).

Returns

Returns a Promise resolving to an object with the following fields:

{
  transactionHash?: string
}

favoriteTrack

favoriteTrack(params, requestInit?)

Favorite a track

Example:

await audiusSdk.tracks.favoriteTrack({
  trackId: 'x5pJ3Az'
  userId: "7eP5n",
});

Params

Create an object with the following fields and pass it as the first argument, as shown in the example above.

{
  isSaveOfRepost: boolean
}

You can pass an optional RequestInit object as the second argument to customize the underlying fetch request (e.g. set custom headers, abort signal, etc.).

Returns

Returns a Promise resolving to an object with the following fields:

{
  transactionHash?: string
}

unfavoriteTrack

unfavoriteTrack(params, requestInit?)

Unfavorite a track

Example:

await audiusSdk.tracks.unfavoriteTrack({
  trackId: 'x5pJ3Az'
  userId: "7eP5n",
});

Params

Create an object with the following fields and pass it as the first argument, as shown in the example above.

You can pass an optional RequestInit object as the second argument to customize the underlying fetch request (e.g. set custom headers, abort signal, etc.).

Returns

Returns a Promise resolving to an object with the following fields:

{
  transactionHash?: string
}

repostTrack

repostTrack(params, requestInit?)

Repost a track

Example:

await audiusSdk.tracks.repostTrack({
  trackId: 'x5pJ3Az'
  userId: "7eP5n",
});

Params

Create an object with the following fields and pass it as the first argument, as shown in the example above.

{
  isRepostOfRepost: boolean
}

You can pass an optional RequestInit object as the second argument to customize the underlying fetch request (e.g. set custom headers, abort signal, etc.).

Returns

Returns a Promise resolving to an object with the following fields:

{
  transactionHash?: string
}

unrepostTrack

unrepostTrack(params, requestInit?)

Unrepost a track

Example:

await audiusSdk.tracks.unrepostTrack({
  trackId: 'x5pJ3Az',
  userId: '7eP5n',
})

Params

Create an object with the following fields and pass it as the first argument, as shown in the example above.

You can pass an optional RequestInit object as the second argument to customize the underlying fetch request (e.g. set custom headers, abort signal, etc.).

Returns

Returns a Promise resolving to an object with the following fields:

{
  transactionHash?: string
}

Type Reference

TrackResponse

CreateTrackRequestBody

Metadata object for creating a new track. Fields marked Required must be provided.

UpdateTrackRequestBody

Metadata object for updating an existing track. All fields are optional — only include the fields you want to change. Omitted fields retain their current values.

AccessGate

AccessGate is a union type representing the conditions required to access a gated track. Used by both streamConditions and downloadConditions. Provide one of the following:

FollowGate

Require the listener to follow a specific user.

{
  followUserId: number // The user ID that must be followed
}

TipGate

Require the listener to have tipped a specific user.

{
  tipUserId: number // The user ID that must be tipped
}

PurchaseGate

Require the listener to purchase access with USDC.

{
  usdcPurchase: {
    price: number // Price in cents
    splits: Array<{
      userId: number // User ID of the payment recipient
      percentage: number // Percentage of the price (0-100)
    }>
  }
}

TokenGate

Require the listener to hold a specific SPL token.

{
  tokenGate: {
    tokenMint: string // The mint address of the SPL token
    tokenAmount: number // The minimum amount of the token required
  }
}

const metadata = {
  title: 'Premium Track',
  genre: 'Electronic',
  trackCid: '...',
  isStreamGated: true,
  streamConditions: {
    usdcPurchase: {
      price: 199, // $1.99 in cents
      splits: [{ userId: 12345, percentage: 100 }],
    },
  },
}

FieldVisibility

Controls which track fields are publicly visible. Each field is a boolean.

{
  mood: boolean
  tags: boolean
  genre: boolean
  share: boolean
  playCount: boolean
  remixes: boolean
}

RemixParentWrite

Identifies the parent track(s) that a remix is derived from.

{
  tracks: Array<{
    parentTrackId: string // The ID of the parent track
  }>
}

const metadata = {
  title: 'My Remix',
  genre: 'Electronic',
  trackCid: '...',
  remixOf: {
    tracks: [{ parentTrackId: 'D7KyD' }],
  },
}

StemParent

Identifies the parent track when uploading a stem (e.g. vocals, drums, bass).

{
  category: string // Stem category (e.g. 'VOCAL', 'DRUMS', 'BASS', 'INSTRUMENTAL', 'OTHER')
  parentTrackId: number // The numeric ID of the parent track
}

DdexResourceContributor

Represents a contributor to the track (used for DDEX metadata).

{
  name: string            // Contributor name
  roles: string[]         // Contributor roles (e.g. 'Composer', 'Lyricist')
  sequenceNumber?: number // Optional ordering index
}

DdexRightsController

Represents the rights controller for the track (used for DDEX metadata).

{
  name: string               // Rights controller name
  roles: string[]            // Roles (e.g. 'RightsController')
  rightsShareUnknown?: string // Optional rights share info
}

Genre Values

Valid genre values for the genre field. Use these exact string values:

'Electronic', 'Rock', 'Metal', 'Alternative', 'Hip-Hop/Rap', 'Experimental', 'Punk', 'Folk', 'Pop', 'Ambient', 'Soundtrack', 'World', 'Jazz', 'Acoustic', 'Funk', 'R&B/Soul', 'Devotional', 'Classical', 'Reggae', 'Podcasts', 'Country', 'Spoken Word', 'Comedy', 'Blues', 'Kids', 'Audiobooks', 'Latin', 'Lo-Fi', 'Hyperpop', 'Dancehall', 'Techno', 'Trap', 'House', 'Tech House', 'Deep House', 'Disco', 'Electro', 'Jungle', 'Progressive House', 'Hardstyle', 'Glitch Hop', 'Trance', 'Future Bass', 'Future House', 'Tropical House', 'Downtempo', 'Drum & Bass', 'Dubstep', 'Jersey Club', 'Vaporwave', 'Moombahton'

Mood Values

Valid mood values for the mood field. Use these exact string values:

'Peaceful', 'Romantic', 'Sentimental', 'Tender', 'Easygoing', 'Yearning', 'Sophisticated', 'Sensual', 'Cool', 'Gritty', 'Melancholy', 'Serious', 'Brooding', 'Fiery', 'Defiant', 'Aggressive', 'Rowdy', 'Excited', 'Energizing', 'Empowering', 'Stirring', 'Upbeat', 'Other'