Spotify Search API: Query Syntax, Limits and 2026 Changes

The Spotify search API is one endpoint, GET https://api.spotify.com/v1/search, that takes a text query and returns matching tracks, artists, albums, playlists, shows, episodes or audiobooks. It still works the way most tutorials describe, but 2026 changed the numbers: development-mode apps now get at most 10 results per page, need a Premium account and can have only 5 users. This guide covers the query syntax, authentication, IDs, limits and the changes that break older code.

How does the Spotify search endpoint work?

Two parameters are required: q, the search text, and type, a comma-separated list of what to search. The rest are optional. Per the search reference:

The response has one paging object per type you asked for (tracks, artists and so on), each with items, next, limit, offset and total.

How do you write a Spotify search query?

Plain words match anywhere. To narrow a search, add field filters to q. Each filter only applies to some types:

Filters combine with plain text: q=airbag artist:radiohead year:1997 with type=track finds that one song. Searching by isrc: is the most reliable way to match a track you already know from another source, because the ISRC identifies the recording itself.

How do you authenticate?

Search reads no user data, so the client credentials flow is enough: exchange your app's client id and secret for a token, then send it as a bearer token. Tokens last 3,600 seconds, so cache one and reuse it.

TOKEN=$(curl -s -X POST "https://accounts.spotify.com/api/token" \
  -u "$SPOTIFY_CLIENT_ID:$SPOTIFY_CLIENT_SECRET" \
  -d "grant_type=client_credentials" | jq -r .access_token)

curl -G "https://api.spotify.com/v1/search" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "q=airbag artist:radiohead" \
  --data-urlencode "type=track" \
  --data-urlencode "market=GB" \
  --data-urlencode "limit=10"

The same call in Python:

import os
import requests

token = requests.post(
    "https://accounts.spotify.com/api/token",
    auth=(os.environ["SPOTIFY_CLIENT_ID"], os.environ["SPOTIFY_CLIENT_SECRET"]),
    data={"grant_type": "client_credentials"},
).json()["access_token"]

res = requests.get(
    "https://api.spotify.com/v1/search",
    headers={"Authorization": f"Bearer {token}"},
    params={"q": "airbag artist:radiohead", "type": "track", "market": "GB", "limit": 10},
)
for track in res.json()["tracks"]["items"]:
    print(track["id"], track["name"], track["artists"][0]["name"])

What is a Spotify ID, URI and URL?

Every result carries an id. Spotify's IDs and URIs page defines the ID as the base-62 identifier at the end of a Spotify URI. Track, artist, album and playlist IDs are typically 22 characters long. The same item appears in three forms:

To turn a pasted link into an ID, take the path segment after /track/, /artist/ or /album/ and drop any ?si= query string. Not every Spotify identifier is 22 characters: user IDs and category IDs are ordinary strings, so do not validate on length alone.

What are the Spotify search API limits?

Spotify counts requests over a rolling 30-second window and does not publish the numbers. When you go over, you get HTTP 429 with a Retry-After header in seconds; wait that long before retrying. Since July 2026, development-mode quota is counted per developer account instead of per app, and a quota error carries "reason": "QUOTA_EXCEEDED".

The bigger limits are on who can use the API at all:

• Development mode is now for learning, experiments and non-commercial personal projects. Since February 2026 the app owner needs Spotify Premium, and each app can have 5 authorised users.
• Extended quota mode, for production, has only been open to organisations since May 2025: a registered business with a launched service and at least 250,000 monthly active users, with review taking up to six weeks.

What changed in the Spotify Web API in 2024–2026?

If a tutorial's code fails, it was probably written before one of these:

The February 2026 migration guide also removed batch lookups such as GET /tracks?ids=, artist top tracks and the browse endpoints, and deprecated fields including popularity, genres and followers. Code that sorts search results by popularity needs another signal.

Searching Spotify alongside other platforms

If Spotify is one of several sources you search, for example finding an artist on Spotify, SoundCloud and Apple Music together, crawlfeed exposes Spotify search and lookups with the same API key and response shape as its other 26 platforms:

A search costs 1 credit, and artists come back as Profile objects, the same type as a SoundCloud or Apple Music artist. Spotify's Developer Terms apply to Spotify content whichever way you fetch it: they forbid feeding it into AI models and building databases beyond what your app needs, so crawlfeed excludes Spotify from its AI enrichment and raw archive. See the Spotify reference for the parameters, or the SoundCloud API guide for the other big music source.

The short answer

Call GET https://api.spotify.com/v1/search with q, type and a client credentials token. Narrow results with filters such as artist:, year: and isrc:, and page with offset up to 1,000. In development mode you get at most 10 results per page, need Premium and can have 5 users; production access is limited to businesses with 250,000 monthly users. IDs are base-62 strings, typically 22 characters, found at the end of every Spotify URI and URL.