# Search tracks, albums and artists
URL: https://musicapi.com/docs/reference/search-user-service.md

`POST https://api.musicapi.com/api/{integrationUserUUID}/search`

Section: Read and write a user's library.
Product: MusicAPI Core.
Auth: Basic, DevToken, DocsSession (any one of them). Use Basic with your Client ID and Client Secret from your server only.

[Check which services support searching by ISRC](/docs/get-started/services-and-features)


Search Endpoint allows you to search for

- tracks
- albums
- artists

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `integrationUserUUID` | uuid | yes | The connected user: the `integrationUserUUID` from the sign-in callback. |

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `nextParam` | string | no | Parameter returned in the response responsible for pagination. |
| `limitParam` | number | no | 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.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string | yes | One of: track, album, artist. |
| `track` | string | no | Track title |
| `artist` | string | no | Artist name |
| `album` | string | no | Album title |
| `isrc` | string | no | 12-digit code assigned to a unique recording of a specific track |

## Response 200

ok

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `results` | SearchResult[] | yes |  |
| `results[].id` | string | yes |  |
| `results[].type` | string | yes | One of: track, album, artist. |
| `results[].track` | object \| null | yes |  |
| `results[].track.id` | string | yes |  |
| `results[].track.entryId` | string \| null | yes | Identifier 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 | yes |  |
| `results[].track.isrc` | string \| null | yes |  |
| `results[].track.duration` | number \| null | yes |  |
| `results[].track.imageUrl` | string \| null | yes |  |
| `results[].track.previewUrl` | string \| null | yes |  |
| `results[].track.album` | object \| null | yes |  |
| `results[].track.album.name` | string | yes |  |
| `results[].track.album.id` | string \| null | yes |  |
| `results[].track.album.totalItems` | number \| null | yes |  |
| `results[].track.album.artists` | ArtistSimplified[] \| null | yes |  |
| `results[].track.album.artists.id` | string \| null | yes |  |
| `results[].track.album.artists.entryId` | string \| null | yes | Identifier 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 | yes |  |
| `results[].track.album.artists.imageUrl` | string \| null | yes |  |
| `results[].track.album.artists.followers` | number \| null | yes |  |
| `results[].track.artists` | ArtistSimplified[] \| null | yes |  |
| `results[].track.artists.id` | string \| null | yes |  |
| `results[].track.artists.entryId` | string \| null | yes | Identifier 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 | yes |  |
| `results[].track.artists.imageUrl` | string \| null | yes |  |
| `results[].track.artists.followers` | number \| null | yes |  |
| `results[].track.isAvailable` | boolean \| null | no | 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 | no |  |
| `results[].album` | object \| null | yes |  |
| `results[].album.id` | string | yes |  |
| `results[].album.name` | string | yes |  |
| `results[].album.totalItems` | number \| null | yes |  |
| `results[].album.imageUrl` | string \| null | yes |  |
| `results[].album.artists` | ArtistSimplified[] \| null | yes |  |
| `results[].album.artists.id` | string \| null | yes |  |
| `results[].album.artists.entryId` | string \| null | yes | Identifier 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 | yes |  |
| `results[].album.artists.imageUrl` | string \| null | yes |  |
| `results[].album.artists.followers` | number \| null | yes |  |
| `results[].artist` | object \| null | yes |  |
| `results[].artist.id` | string | yes |  |
| `results[].artist.entryId` | string \| null | yes | Identifier 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 | yes |  |
| `results[].artist.imageUrl` | string \| null | yes |  |
| `results[].artist.followers` | number \| null | yes |  |
| `nextParam` | string \| null | yes |  |
| `totalItems` | number \| null | yes |  |

```json
{
  "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`.

## Example

```bash
curl -X POST "https://api.musicapi.com/api/{integrationUserUUID}/search" \
  -u "$MUSICAPI_CLIENT_ID:$MUSICAPI_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"type":"track","track":"Numb","artist":"Linkin Park","album":"Meteora","isrc":"USWB10300474"}'
```