Skip to the content
Get an API key
  1. API reference
  2. Read and write a user's library

Search tracks, albums and artists

POST/api/{integrationUserUUID}/search
CoreAuthBasicDevTokenDocsSessionToken

Check which services support searching by ISRC

Search Endpoint allows you to search for

- tracks - albums - artists

Path parameters

integrationUserUUID
uuidrequired

The connected user: the integrationUserUUID from the sign-in callback.

Query parameters

nextParam
string

Parameter returned in the response responsible for pagination.

limitParam
number

Specifies the maximum number of results per request, adjusted based on the limitations of the respective music service. Ignored if the service doesn't support such a limit.

Request body

application/json · required

type
string
requiredOne of: track, album, artist
track
string
Track title
artist
string
Artist name
album
string
Album title
isrc
string
12-digit code assigned to a unique recording of a specific track

Response

200application/json · SearchResponseok
results
SearchResult[]
required
results[].id
string
required
results[].type
string
requiredOne of: track, album, artist
results[].track
object | null
required
results[].track.id
string
required
results[].track.entryId
string | null
requiredIdentifier associated with a tracks within a specific collection. It is used to identify a particular instance of a track within a playlist or a user's library. Track entry id can be obtained during fetching playlist items or user's library.
results[].track.name
string
required
results[].track.isrc
string | null
required
results[].track.duration
number | null
required
results[].track.imageUrl
string | null
required
results[].track.previewUrl
string | null
required
results[].track.album
object | null
required
results[].track.album.name
string
required
results[].track.album.id
string | null
required
results[].track.album.totalItems
number | null
required
results[].track.album.artists
ArtistSimplified[] | null
required
results[].track.album.artists.id
string | null
required
results[].track.album.artists.entryId
string | null
requiredIdentifier associated with an artist within a user's library. Artist entry id can be obtained during fetching artists from user's library.
results[].track.album.artists.name
string
required
results[].track.album.artists.imageUrl
string | null
required
results[].track.album.artists.followers
number | null
required
results[].track.artists
ArtistSimplified[] | null
required
results[].track.artists.id
string | null
required
results[].track.artists.entryId
string | null
requiredIdentifier associated with an artist within a user's library. Artist entry id can be obtained during fetching artists from user's library.
results[].track.artists.name
string
required
results[].track.artists.imageUrl
string | null
required
results[].track.artists.followers
number | null
required
results[].track.isAvailable
boolean | null
Indicates whether the track is currently available for playback on the music service. For Spotify: false for local files or greyed-out tracks (copyright lost), true for playable tracks, null when unknown.
results[].track.dateAdded
string | null
results[].album
object | null
required
results[].album.id
string
required
results[].album.name
string
required
results[].album.totalItems
number | null
required
results[].album.imageUrl
string | null
required
results[].album.artists
ArtistSimplified[] | null
required
results[].album.artists.id
string | null
required
results[].album.artists.entryId
string | null
requiredIdentifier associated with an artist within a user's library. Artist entry id can be obtained during fetching artists from user's library.
results[].album.artists.name
string
required
results[].album.artists.imageUrl
string | null
required
results[].album.artists.followers
number | null
required
results[].artist
object | null
required
results[].artist.id
string
required
results[].artist.entryId
string | null
requiredIdentifier associated with an artist within a user's library. Artist entry id can be obtained during fetching artists from user's library.
results[].artist.name
string
required
results[].artist.imageUrl
string | null
required
results[].artist.followers
number | null
required
nextParam
string | null
required
totalItems
number | null
required
Example answer
{
  "results": [
    {
      "id": "57bgtoPSgt236HzfBOd8kj",
      "type": "track",
      "track": null,
      "album": null,
      "artist": null
    }
  ],
  "nextParam": "eyJvZmZzZXQiOjEwfQ==",
  "totalItems": 0
}

Errors

404

Your account has no connected user with this uuid, or the item does not exist.

412

The user must sign in again (IntegrationUserNotAuthenticated).

429

Too many requests. Wait for the seconds in Retry-After.