Docs menu

Spotify API endpoint

Spotify Search API

Returns Spotify catalog search results across tracks, artists, albums, playlists, shows, episodes, audiobooks, and top results. Caller-supplied Spotify bearer or client tokens are not required.

GETapiKey3 credits/requestSpotifyspotify.searchCatalogResponseDoc/spotify/search

Endpoint facts

Method: GET
API path: /spotify/search
Auth: apiKey
Credits: 3 credits/request
Charged on: Successful 2xx responses only
Platform: Spotify
Response schema: #/definitions/spotify.searchCatalogResponseDoc
MCP tool: spotify_search

Spotify scraping API Try Spotify Search API in Playground Spotify API documentation

How this endpoint behaves

MCP tool: spotify_search

Path/query/body parameters:

q query string, required. Search term.
offset query integer, optional. Search offset. Defaults to 0.
limit query integer, optional. Result limit per section, clamped to 1-50. Defaults to 10.
number_of_top_results query integer, optional. Top result limit, clamped to 1-50. Defaults to 5.
include_audiobooks query boolean, optional. Includes audiobook results when requested.
include_artist_has_concerts_field query boolean, optional. Requests Spotify artist concert availability fields.
include_pre_releases query boolean, optional. Includes pre-release results when requested.
include_album_pre_releases query boolean, optional. Includes album pre-release results when requested.
include_authors query boolean, optional. Includes authors when requested.
include_episode_content_ratings_v2 query boolean, optional. Includes Spotify episode content ratings v2 when requested.
is_prefix query boolean, optional. Treats the search term as a prefix when provided.

Notable response behavior:

Upstream failures return 503.
The response includes a de-duplicated results array plus type-specific arrays for common Spotify catalog entity types.
topResults reflects Spotify's top-result container and may overlap with the de-duplicated results array.

Live monitoring

Monitored request: GET /spotify/search?include_audiobooks=true&include_pre_releases=true&limit=10&number_of_top_results=5&q=hello
Checks passed, 7 days to 14 Oct 2026: 100%
Median response time: 1.92 s

Current status of every endpoint

Sampled response

Request, 14 Oct 2026: GET /spotify/search?include_audiobooks=true&include_pre_releases=true&limit=10&number_of_top_results=5&q=hello
Items in results: 122
Fields filled in every checked item: 2
Fields empty in some or all items: 7

Field	Filled in, of 122 checked	Values in the sample
uri	122	“spotify:album:0Wtp1qSPNv4SmtwmPf8x9n” and 121 other values
type	82	Podcast (18), Audiobook (10), Episode (10) and 5 more
title	122	“Hello” and 109 other values
imageUrl	89	i.scdn.co and 5 other hosts
images	89	median 3 entries
externalUrl	109	open.spotify.com
description	26	median 615 characters
subtitle	18	“juilet” and 17 other values
publisher	18	“juilet” and 17 other values

Request parameters

Parameter	Type	Required	Description	Example
q	string	Yes	Search term	hello
offset	integer	No	Search offset	0
limit	integer	No	Result limit per section, clamped to 1-50	10
number_of_top_results	integer	No	Top result limit, clamped to 1-50	5
include_audiobooks	boolean	No	Include audiobook results	true
include_artist_has_concerts_field	boolean	No	Include artist concert availability fields	false
include_pre_releases	boolean	No	Include pre-release results	true
include_album_pre_releases	boolean	No	Include album pre-release results	false
include_authors	boolean	No	Include authors	false
include_episode_content_ratings_v2	boolean	No	Include Spotify episode content ratings v2	false
is_prefix	boolean	No	Treat the search term as a prefix	false
x-api-key (header)	string	Yes	API key required

cURL example

curl -X GET "https://api.crawlora.net/api/v1/spotify/search?q=hello&limit=10&include_audiobooks=true&include_artist_has_concerts_field=true&include_pre_releases=true&include_album_pre_releases=true&include_authors=true&include_episode_content_ratings_v2=true&is_prefix=true" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Example JSON response

{
  "code": 200,
  "msg": "OK",
  "data": {
    "searchTerm": "hello",
    "offset": 0,
    "limit": 10,
    "topResults": [
      {
        "uri": "spotify:track:example",
        "type": "Track",
        "title": "Hello",
        "externalUrl": "https://open.spotify.com/track/example"
      }
    ],
    "results": [
      {
        "uri": "spotify:artist:example",
        "type": "Artist",
        "title": "Example Artist",
        "externalUrl": "https://open.spotify.com/artist/example"
      }
    ],
    "artists": [
      {
        "uri": "spotify:artist:example",
        "type": "Artist",
        "title": "Example Artist",
        "externalUrl": "https://open.spotify.com/artist/example"
      }
    ],
    "meta": {
      "operationName": "searchDesktop",
      "appVersion": "1.2.90.400.g1e02cab1",
      "resultCount": 1,
      "artistCount": 1,
      "topCount": 1,
      "fetchedAt": "2026-05-13T15:22:41Z"
    }
  }
}

Request schema

No body schema

Response schema

#/definitions/spotify.searchCatalogResponseDoc

Field	Type	Required	Example	Description
code	integer	No		Code is the HTTP status code or a custom code used to indicate the result of the request @example 200
data	spotify.SearchResponse	No
data.albums	array	No		Albums that matched the search term. SearchResultSummary record, 12 fields: description, externalUrl, imageUrl, images, publisher, subtitle, title, type, uri. Described under Spotify album API.
data.artists	array	No		Artists that matched the search term. SearchResultSummary record, 12 fields: description, externalUrl, imageUrl, images, publisher, subtitle, title, type, uri. Described under Spotify album API.
data.audiobooks	array	No		Audiobooks that matched the search term. SearchResultSummary record, 12 fields: description, externalUrl, imageUrl, images, publisher, subtitle, title, type, uri. Described under Spotify album API.
data.episodes	array	No		Podcast episodes that matched the search term. SearchResultSummary record, 12 fields: description, externalUrl, imageUrl, images, publisher, subtitle, title, type, uri. Described under Spotify album API.
data.limit	integer	No	20	Maximum number of results requested per section.
data.meta	object	No		Details about this response.
data.meta.albumCount	integer	No	3	Number of albums returned.
data.meta.appVersion	string	No	1.2.90.403.gf901f20f	Version of the Spotify web player the data was read from.
data.meta.artistCount	integer	No	5	Number of artists returned.
data.meta.audiobookCount	integer	No	2	Number of audiobooks returned.
data.meta.episodeCount	integer	No	2	Number of episodes returned.
data.meta.fetchedAt	string	No	2026-05-13T20:41:12Z	Time the data was fetched, in UTC (RFC 3339).
data.meta.operationName	string	No	searchDesktop	Name of the Spotify web player operation that returned the data.
data.meta.playlistCount	integer	No	2	Number of playlists returned.
data.meta.resultCount	integer	No	22	Total number of results returned.
data.meta.showCount	integer	No	4	Number of shows returned.
data.meta.topCount	integer	No	3	Number of top results returned.
data.meta.trackCount	integer	No	2	Number of tracks returned.
data.meta.userCount	integer	No	2	Number of user profiles returned.
data.offset	integer	No	0	Position of the first result returned.
data.playlists	array	No		Playlists that matched the search term. SearchResultSummary record, 12 fields: description, externalUrl, imageUrl, images, publisher, subtitle, title, type, uri. Described under Spotify album API.
data.results	array	No		All results found, across every type. SearchResultSummary record, 12 fields: description, externalUrl, imageUrl, images, publisher, subtitle, title, type, uri. Described under Spotify album API.
data.searchTerm	string	No	hello	Search term that was run.
data.shows	array	No		Podcast shows that matched the search term. SearchResultSummary record, 12 fields: description, externalUrl, imageUrl, images, publisher, subtitle, title, type, uri. Described under Spotify album API.
data.topResults	array	No		Best matches across all result types. SearchResultSummary record, 12 fields: description, externalUrl, imageUrl, images, publisher, subtitle, title, type, uri. Described under Spotify album API.
data.tracks	array	No		Tracks that matched the search term. SearchResultSummary record, 12 fields: description, externalUrl, imageUrl, images, publisher, subtitle, title, type, uri. Described under Spotify album API.
data.users	array	No		User profiles that matched the search term. SearchResultSummary record, 12 fields: description, externalUrl, imageUrl, images, publisher, subtitle, title, type, uri. Described under Spotify album API.
msg	unknown	No		Msg is the message that describes the result of the request @example "Request successful"

Failure responses

Status	Description	Schema
400	Missing or invalid parameters	#/definitions/app.Response
429	Rate limit exceeded	#/definitions/app.Response
503	Spotify upstream request failed	#/definitions/app.Response

Code examples

Use environment variables for secrets and keep Crawlora API keys server-side.

curl -X GET "https://api.crawlora.net/api/v1/spotify/search?q=hello&limit=10&include_audiobooks=true&include_artist_has_concerts_field=true&include_pre_releases=true&include_album_pre_releases=true&include_authors=true&include_episode_content_ratings_v2=true&is_prefix=true" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Shared guides

Authentication Errors and retries Rate limits and credits Pricing MCP server Acceptable use

More Spotify endpoint docs Spotify scraping API Spotify album API documentation Spotify album tracks API documentation Spotify Albums Search API documentation Spotify artist API documentation Spotify artist albums API documentation Spotify artist playlists API documentation

Open in Playground Back to group

Docs menu

Spotify API endpoint

Spotify Search API

Returns Spotify catalog search results across tracks, artists, albums, playlists, shows, episodes, audiobooks, and top results. Caller-supplied Spotify bearer or client tokens are not required.

GETapiKey3 credits/requestSpotifyspotify.searchCatalogResponseDoc/spotify/search

Endpoint facts

Method: GET
API path: /spotify/search
Auth: apiKey
Credits: 3 credits/request
Charged on: Successful 2xx responses only
Platform: Spotify
Response schema: #/definitions/spotify.searchCatalogResponseDoc
MCP tool: spotify_search

Spotify scraping API Try Spotify Search API in Playground Spotify API documentation

How this endpoint behaves

MCP tool: spotify_search

Path/query/body parameters:

q query string, required. Search term.
offset query integer, optional. Search offset. Defaults to 0.
limit query integer, optional. Result limit per section, clamped to 1-50. Defaults to 10.
number_of_top_results query integer, optional. Top result limit, clamped to 1-50. Defaults to 5.
include_audiobooks query boolean, optional. Includes audiobook results when requested.
include_artist_has_concerts_field query boolean, optional. Requests Spotify artist concert availability fields.
include_pre_releases query boolean, optional. Includes pre-release results when requested.
include_album_pre_releases query boolean, optional. Includes album pre-release results when requested.
include_authors query boolean, optional. Includes authors when requested.
include_episode_content_ratings_v2 query boolean, optional. Includes Spotify episode content ratings v2 when requested.
is_prefix query boolean, optional. Treats the search term as a prefix when provided.

Notable response behavior:

Upstream failures return 503.
The response includes a de-duplicated results array plus type-specific arrays for common Spotify catalog entity types.
topResults reflects Spotify's top-result container and may overlap with the de-duplicated results array.

Live monitoring

Monitored request: GET /spotify/search?include_audiobooks=true&include_pre_releases=true&limit=10&number_of_top_results=5&q=hello
Checks passed, 7 days to 14 Oct 2026: 100%
Median response time: 1.92 s

Current status of every endpoint

Sampled response

Request, 14 Oct 2026: GET /spotify/search?include_audiobooks=true&include_pre_releases=true&limit=10&number_of_top_results=5&q=hello
Items in results: 122
Fields filled in every checked item: 2
Fields empty in some or all items: 7

Field	Filled in, of 122 checked	Values in the sample
uri	122	“spotify:album:0Wtp1qSPNv4SmtwmPf8x9n” and 121 other values
type	82	Podcast (18), Audiobook (10), Episode (10) and 5 more
title	122	“Hello” and 109 other values
imageUrl	89	i.scdn.co and 5 other hosts
images	89	median 3 entries
externalUrl	109	open.spotify.com
description	26	median 615 characters
subtitle	18	“juilet” and 17 other values
publisher	18	“juilet” and 17 other values

Request parameters

Parameter	Type	Required	Description	Example
q	string	Yes	Search term	hello
offset	integer	No	Search offset	0
limit	integer	No	Result limit per section, clamped to 1-50	10
number_of_top_results	integer	No	Top result limit, clamped to 1-50	5
include_audiobooks	boolean	No	Include audiobook results	true
include_artist_has_concerts_field	boolean	No	Include artist concert availability fields	false
include_pre_releases	boolean	No	Include pre-release results	true
include_album_pre_releases	boolean	No	Include album pre-release results	false
include_authors	boolean	No	Include authors	false
include_episode_content_ratings_v2	boolean	No	Include Spotify episode content ratings v2	false
is_prefix	boolean	No	Treat the search term as a prefix	false
x-api-key (header)	string	Yes	API key required

cURL example

curl -X GET "https://api.crawlora.net/api/v1/spotify/search?q=hello&limit=10&include_audiobooks=true&include_artist_has_concerts_field=true&include_pre_releases=true&include_album_pre_releases=true&include_authors=true&include_episode_content_ratings_v2=true&is_prefix=true" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Example JSON response

{
  "code": 200,
  "msg": "OK",
  "data": {
    "searchTerm": "hello",
    "offset": 0,
    "limit": 10,
    "topResults": [
      {
        "uri": "spotify:track:example",
        "type": "Track",
        "title": "Hello",
        "externalUrl": "https://open.spotify.com/track/example"
      }
    ],
    "results": [
      {
        "uri": "spotify:artist:example",
        "type": "Artist",
        "title": "Example Artist",
        "externalUrl": "https://open.spotify.com/artist/example"
      }
    ],
    "artists": [
      {
        "uri": "spotify:artist:example",
        "type": "Artist",
        "title": "Example Artist",
        "externalUrl": "https://open.spotify.com/artist/example"
      }
    ],
    "meta": {
      "operationName": "searchDesktop",
      "appVersion": "1.2.90.400.g1e02cab1",
      "resultCount": 1,
      "artistCount": 1,
      "topCount": 1,
      "fetchedAt": "2026-05-13T15:22:41Z"
    }
  }
}

Request schema

No body schema

Response schema

#/definitions/spotify.searchCatalogResponseDoc

Field	Type	Required	Example	Description
code	integer	No		Code is the HTTP status code or a custom code used to indicate the result of the request @example 200
data	spotify.SearchResponse	No
data.albums	array	No		Albums that matched the search term. SearchResultSummary record, 12 fields: description, externalUrl, imageUrl, images, publisher, subtitle, title, type, uri. Described under Spotify album API.
data.artists	array	No		Artists that matched the search term. SearchResultSummary record, 12 fields: description, externalUrl, imageUrl, images, publisher, subtitle, title, type, uri. Described under Spotify album API.
data.audiobooks	array	No		Audiobooks that matched the search term. SearchResultSummary record, 12 fields: description, externalUrl, imageUrl, images, publisher, subtitle, title, type, uri. Described under Spotify album API.
data.episodes	array	No		Podcast episodes that matched the search term. SearchResultSummary record, 12 fields: description, externalUrl, imageUrl, images, publisher, subtitle, title, type, uri. Described under Spotify album API.
data.limit	integer	No	20	Maximum number of results requested per section.
data.meta	object	No		Details about this response.
data.meta.albumCount	integer	No	3	Number of albums returned.
data.meta.appVersion	string	No	1.2.90.403.gf901f20f	Version of the Spotify web player the data was read from.
data.meta.artistCount	integer	No	5	Number of artists returned.
data.meta.audiobookCount	integer	No	2	Number of audiobooks returned.
data.meta.episodeCount	integer	No	2	Number of episodes returned.
data.meta.fetchedAt	string	No	2026-05-13T20:41:12Z	Time the data was fetched, in UTC (RFC 3339).
data.meta.operationName	string	No	searchDesktop	Name of the Spotify web player operation that returned the data.
data.meta.playlistCount	integer	No	2	Number of playlists returned.
data.meta.resultCount	integer	No	22	Total number of results returned.
data.meta.showCount	integer	No	4	Number of shows returned.
data.meta.topCount	integer	No	3	Number of top results returned.
data.meta.trackCount	integer	No	2	Number of tracks returned.
data.meta.userCount	integer	No	2	Number of user profiles returned.
data.offset	integer	No	0	Position of the first result returned.
data.playlists	array	No		Playlists that matched the search term. SearchResultSummary record, 12 fields: description, externalUrl, imageUrl, images, publisher, subtitle, title, type, uri. Described under Spotify album API.
data.results	array	No		All results found, across every type. SearchResultSummary record, 12 fields: description, externalUrl, imageUrl, images, publisher, subtitle, title, type, uri. Described under Spotify album API.
data.searchTerm	string	No	hello	Search term that was run.
data.shows	array	No		Podcast shows that matched the search term. SearchResultSummary record, 12 fields: description, externalUrl, imageUrl, images, publisher, subtitle, title, type, uri. Described under Spotify album API.
data.topResults	array	No		Best matches across all result types. SearchResultSummary record, 12 fields: description, externalUrl, imageUrl, images, publisher, subtitle, title, type, uri. Described under Spotify album API.
data.tracks	array	No		Tracks that matched the search term. SearchResultSummary record, 12 fields: description, externalUrl, imageUrl, images, publisher, subtitle, title, type, uri. Described under Spotify album API.
data.users	array	No		User profiles that matched the search term. SearchResultSummary record, 12 fields: description, externalUrl, imageUrl, images, publisher, subtitle, title, type, uri. Described under Spotify album API.
msg	unknown	No		Msg is the message that describes the result of the request @example "Request successful"

Failure responses

Status	Description	Schema
400	Missing or invalid parameters	#/definitions/app.Response
429	Rate limit exceeded	#/definitions/app.Response
503	Spotify upstream request failed	#/definitions/app.Response

Code examples

Use environment variables for secrets and keep Crawlora API keys server-side.

curl -X GET "https://api.crawlora.net/api/v1/spotify/search?q=hello&limit=10&include_audiobooks=true&include_artist_has_concerts_field=true&include_pre_releases=true&include_album_pre_releases=true&include_authors=true&include_episode_content_ratings_v2=true&is_prefix=true" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Shared guides

Authentication Errors and retries Rate limits and credits Pricing MCP server Acceptable use

Open in Playground Back to group

Spotify Search API

Endpoint facts

How this endpoint behaves

Live monitoring

Sampled response

Request parameters

cURL example

Example JSON response

Failure responses

Code examples

Shared guides

Related

Spotify Search API

Endpoint facts

How this endpoint behaves

Live monitoring

Sampled response

Request parameters

cURL example

Example JSON response

Failure responses

Code examples

Shared guides

Related