Search for Item

Changed on Apr 30, 2026

Get Spotify catalog information about albums, artists, playlists, tracks, shows, episodes or audiobooks that match a keyword string. Audiobooks are only available within the US, UK, Canada, Ireland, New Zealand and Australia markets.

get/search

Request

Base URL
https://api.spotify.com/v1
URL
https://api.spotify.com/v1/search
Auth
OAuth 2
Authorization code: https://accounts.spotify.com/authorize
Token URL: https://accounts.spotify.com/api/token

Query parameters

qstring required

Your search query.

You can narrow down your search using field filters. The available filters are album, artist, track, year, upc, tag:hipster, tag:new, isrc, and genre. Each field filter only applies to certain result types.

The artist and year filters can be used while searching albums, artists and tracks. You can filter on a single year or a range (e.g. 1955-1960). The album filter can be used while searching albums and tracks. The genre filter can be used while searching artists and tracks. The isrc and track filters can be used while searching tracks. The upc, tag:new and tag:hipster filters can only be used while searching albums. The tag:new filter will return albums released in the past two weeks and tag:hipster can be used to return only albums with the lowest 10% popularity.

Example:remaster%20track:Doxy%20artist:Miles%20Davis

typestring[] required

A comma-separated list of item types to search across. Search results include hits from all the specified item types. For example: q=abacab&type=album,track returns both albums and tracks matching "abacab".

marketstring

An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that is available in that market will be returned. If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter. Note: If neither market or user country are provided, the content is considered unavailable for the client. Users can view the country that is associated with their account in the account settings.

Example:ES

limitinteger

The maximum number of results to return in each item type.

Example:10

offsetinteger

The index of the first result to return. Use with limit to get the next page of search results.

Example:5

include_external'audio'

If include_external=audio is specified it signals that the client can play externally hosted audio content, and marks the content as playable in the response. By default externally hosted audio content is marked as unplayable in the response.

Response

Search response

Example response

{
  "tracks": {
    "href": "https://api.spotify.com/v1/me/shows?offset=0&limit=20\n",
    "limit": 20,
    "next": "https://api.spotify.com/v1/me/shows?offset=1&limit=1",
    "previous": "https://api.spotify.com/v1/me/shows?offset=1&limit=1",
    "total": 4,
    "items": [
      {
        "album": {
          "album_type": "compilation",
          "total_tracks": 9,
          "available_markets": [
            "CA",
            "BR",
            "IT"
          ],
          "id": "2up3OPMp9Tb4dAKM2erWXQ",
          "images": [
            {
              "url": "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228\n",
              "height": 300,
              "width": 300
            }
          ],
          "release_date": "1981-12",
          "release_date_precision": "year",
          "uri": "spotify:album:2up3OPMp9Tb4dAKM2erWXQ"
        }
      }
    ]
  },
  "artists": {
    "href": "https://api.spotify.com/v1/me/shows?offset=0&limit=20\n",
    "limit": 20,
    "next": "https://api.spotify.com/v1/me/shows?offset=1&limit=1",
    "previous": "https://api.spotify.com/v1/me/shows?offset=1&limit=1",
    "total": 4,
    "items": [
      {
        "genres": [
          "Prog rock",
          "Grunge"
        ],
        "images": [
          {
            "url": "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228\n",
            "height": 300,
            "width": 300
          }
        ]
      }
    ]
  },
  "albums": {
    "href": "https://api.spotify.com/v1/me/shows?offset=0&limit=20\n",
    "limit": 20,
    "next": "https://api.spotify.com/v1/me/shows?offset=1&limit=1",
    "previous": "https://api.spotify.com/v1/me/shows?offset=1&limit=1",
    "total": 4,
    "items": [
      {
        "album_type": "compilation",
        "total_tracks": 9,
        "available_markets": [
          "CA",
          "BR",
          "IT"
        ],
        "id": "2up3OPMp9Tb4dAKM2erWXQ",
        "images": [
          {
            "url": "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228\n",
            "height": 300,
            "width": 300
          }
        ],
        "release_date": "1981-12",
        "release_date_precision": "year",
        "uri": "spotify:album:2up3OPMp9Tb4dAKM2erWXQ"
      }
    ]
  },
  "playlists": {
    "href": "https://api.spotify.com/v1/me/shows?offset=0&limit=20\n",
    "limit": 20,
    "next": "https://api.spotify.com/v1/me/shows?offset=1&limit=1",
    "previous": "https://api.spotify.com/v1/me/shows?offset=1&limit=1",
    "total": 4,
    "items": [
      {
        "images": [
          {
            "url": "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228\n",
            "height": 300,
            "width": 300
          }
        ]
      }
    ]
  },
  "shows": {
    "href": "https://api.spotify.com/v1/me/shows?offset=0&limit=20\n",
    "limit": 20,
    "next": "https://api.spotify.com/v1/me/shows?offset=1&limit=1",
    "previous": "https://api.spotify.com/v1/me/shows?offset=1&limit=1",
    "total": 4,
    "items": [
      {
        "images": [
          {
            "url": "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228\n",
            "height": 300,
            "width": 300
          }
        ]
      }
    ]
  },
  "episodes": {
    "href": "https://api.spotify.com/v1/me/shows?offset=0&limit=20\n",
    "limit": 20,
    "next": "https://api.spotify.com/v1/me/shows?offset=1&limit=1",
    "previous": "https://api.spotify.com/v1/me/shows?offset=1&limit=1",
    "total": 4,
    "items": [
      {
        "audio_preview_url": "https://p.scdn.co/mp3-preview/2f37da1d4221f40b9d1a98cd191f4d6f1646ad17",
        "description": "A Spotify podcast sharing fresh insights on important topics of the moment—in a way only Spotify can. You’ll hear from experts in the music, podcast and tech industries as we discover and uncover stories about our work and the world around us.\n",
        "html_description": "<p>A Spotify podcast sharing fresh insights on important topics of the moment—in a way only Spotify can. You’ll hear from experts in the music, podcast and tech industries as we discover and uncover stories about our work and the world around us.</p>\n",
        "duration_ms": 1686230,
        "href": "https://api.spotify.com/v1/episodes/5Xt5DXGzch68nYYamXrNxZ",
        "id": "5Xt5DXGzch68nYYamXrNxZ",
        "images": [
          {
            "url": "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228\n",
            "height": 300,
            "width": 300
          }
        ],
        "language": "en",
        "languages": [
          "fr",
          "en"
        ],
        "name": "Starting Your Own Podcast: Tips, Tricks, and Advice From Anchor Creators\n",
        "release_date": "1981-12-15",
        "release_date_precision": "day",
        "uri": "spotify:episode:0zLhl3WsOCQHbe1BPTiHgr"
      }
    ]
  },
  "audiobooks": {
    "href": "https://api.spotify.com/v1/me/shows?offset=0&limit=20\n",
    "limit": 20,
    "next": "https://api.spotify.com/v1/me/shows?offset=1&limit=1",
    "previous": "https://api.spotify.com/v1/me/shows?offset=1&limit=1",
    "total": 4,
    "items": [
      {
        "edition": "Unabridged",
        "images": [
          {
            "url": "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228\n",
            "height": 300,
            "width": 300
          }
        ]
      }
    ]
  }
}

Changes

Apr 30, 20261602059e3988 Revision changes
- info
  response property tracks/allOf[subschema #2]/items/items/external_ids reactivated
Feb 28, 20268899d6fd66ee Revision changes
- breaking
  for the query request parameter limit, default value was changed from 20 to 5
- breaking
  for the query request parameter limit, the max was decreased from 50.00 to 10.00
- info
  added the optional property //// to the response with the status
- info
  response property albums/allOf[subschema #2]/items/items/allOf[AlbumBase]/available_markets deprecated
- info
  response property artists/allOf[subschema #2]/items/items/followers deprecated
- info
  response property artists/allOf[subschema #2]/items/items/genres deprecated
- info
  response property artists/allOf[subschema #2]/items/items/popularity deprecated
- info
  response property audiobooks/allOf[subschema #2]/items/items/allOf[AudiobookBase]/available_markets deprecated
- info
  response property audiobooks/allOf[subschema #2]/items/items/allOf[AudiobookBase]/publisher deprecated
- info
  response property playlists/allOf[subschema #2]/items/items/tracks deprecated
- info
  response property shows/allOf[subschema #2]/items/items/allOf[ShowBase]/available_markets deprecated
- info
  response property shows/allOf[subschema #2]/items/items/allOf[ShowBase]/publisher deprecated
- info
  response property tracks/allOf[subschema #2]/items/items/album/allOf[SimplifiedAlbumObject]/allOf[AlbumBase]/available_markets deprecated
- info
  response property tracks/allOf[subschema #2]/items/items/available_markets deprecated
- info
  response property tracks/allOf[subschema #2]/items/items/external_ids deprecated
- info
  response property tracks/allOf[subschema #2]/items/items/linked_from deprecated
- info
  response property tracks/allOf[subschema #2]/items/items/popularity deprecated

Operation history (5 revisions)