Spotify Search API

What is the Spotify Search API?

Pass q plus optional type=tracks|albums|artists|podcasts|episodes (default tracks) and limit (max 50, no cursor). Primary path is web-player Pathfinder GraphQL (same family as /spotify/artist|track|album); Apify scraper is fallthrough only — do not assume one raw schema across both (GraphQL __typename vs flat albumName/isExplicit). Envelope: query, type, fetchedAt, source (pathfinder|apify), results[]. Each result ships a canonical Spotify URI (spotify:track:… not a bare id), url, name, artists (structured on Pathfinder track/album hits), durationMs/durationFormatted, explicit, contentRating, and image. Request freshness is envelope fetchedAt only — not copied onto every row. Pathfinder search (decorateContextTracks) does not expose playCount or playable (absence ≠ false/zero); chain uri into /spotify/track for those. Flat 2 credits on native Pathfinder; Apify fallthrough scales per result. Pass raw=true for per-result upstream payloads (omitted by default; searchTerm is not repeated inside raw).

What you get

• Ranked, structured result list
• Title, URL, author, and thumbnail per result when available
• Engagement metrics where the platform exposes them
• Configurable result limit

Platform limits

Honest ceilings from the upstream platform surface — not Captapi bugs. Unexpected truncation here is usually the platform, not us.

• playCount is not on search.results[] — Pathfinder search hydrate omits stream counts; use /spotify/track or /spotify/album tracks[].
• playable is not on search.results[] — decorateContextTracks omits playability; use /spotify/track.
• fetchedAt is envelope-only — results[] do not carry scrapedAt.

Fill in the parameters below and copy a ready-to-run request, or open the live Playground to run it against your account (no API key paste).

curl "https://api.captapi.com/v1/spotify/search?q=lofi%20beats" \
  -H "Authorization: Bearer capt_live_..."
# or: -H "x-api-key: capt_live_..."

Example response

{
  "success": true,
  "data": {
    "platform": "spotify",
    "query": "lofi beats",
    "type": "tracks",
    "fetchedAt": "2026-08-07T10:56:53.985Z",
    "source": "pathfinder",
    "totalReturned": 5,
    "results": [
      {
        "platform": "spotify",
        "type": "track",
        "uri": "spotify:track:1xqpCUhTXEG3Zj7E6VEyj4",
        "url": "https://open.spotify.com/track/1xqpCUhTXEG3Zj7E6VEyj4",
        "name": "Lodi Dodi",
        "artists": [
          {
            "id": "7hJcb9fa4alzcOq3EaNPoG",
            "uri": "spotify:artist:7hJcb9fa4alzcOq3EaNPoG",
            "name": "Snoop Dogg",
            "url": "https://open.spotify.com/artist/7hJcb9fa4alzcOq3EaNPoG"
          }
        ],
        "album": {
          "id": "0iXJO2ZAfKzNDYa6E4EFfl",
          "uri": "spotify:album:0iXJO2ZAfKzNDYa6E4EFfl",
          "name": "Death Row Greatest Hits",
          "url": "https://open.spotify.com/album/0iXJO2ZAfKzNDYa6E4EFfl"
        },
        "durationMs": 264480,
        "durationFormatted": "4:24",
        "image": "https://i.scdn.co/image/ab67616d0000b2739322ff440b23b5717ddd8c9b",
        "id": "1xqpCUhTXEG3Zj7E6VEyj4",
        "contentRating": "EXPLICIT",
        "explicit": true
      },
      {
        "platform": "spotify",
        "type": "track",
        "uri": "spotify:track:5SFVfPQNHzrsVjO2YmOl7u",
        "url": "https://open.spotify.com/track/5SFVfPQNHzrsVjO2YmOl7u",
        "name": "Lofi Beats",
        "artists": [
          {
            "id": "0uXJZ5oJisbrkihiMUDiya",
            "uri": "spotify:artist:0uXJZ5oJisbrkihiMUDiya",
            "name": "Productivity Booster Music",
            "url": "https://open.spotify.com/artist/0uXJZ5oJisbrkihiMUDiya"
          }
        ],
        "album": {
          "id": "7D6QtZp3B4UAjd9J8hzjS2",
          "uri": "spotify:album:7D6QtZp3B4UAjd9J8hzjS2",
          "name": "All-Day Flow: Lo-Fi Beats for Creative Work",
          "url": "https://open.spotify.com/album/7D6QtZp3B4UAjd9J8hzjS2"
        },
        "durationMs": 158000,
        "durationFormatted": "2:38",
        "image": "https://i.scdn.co/image/ab67616d0000b27356f94cadfab4bf5902a8f30c",
        "id": "5SFVfPQNHzrsVjO2YmOl7u",
        "contentRating": "NONE",
        "explicit": false
      }
    ]
  }
}

Billing metadata is returned in response headers: X-Captapi-Credits (credits charged), X-Captapi-Cache (hit or miss), and X-Captapi-Source. Failed requests (4xx/5xx) are never charged. See the full list of error codes in the error reference.

Response structure

A successful call returns success, cached, creditsUsed, and a data object with the following fields:

Parameters

Authentication: send your key as Authorization: Bearer capt_live_.... A typical call costs 2 credits. Pass cache=true for a free 24h cache hit; default is always fresh.

How it works

1. 1. Sign up — get 100 free credits, no card required.
2. 2. Create a key from your dashboard.
3. 3. Send one request to /v1/spotify/search and parse the JSON response.

Use cases

Frequently asked questions

More Spotify APIs