---
title: "Spotify Search API"
method: GET
path: "/v1/spotify/search"
tags: ["Spotify"]
---

# Spotify Search API

`GET /v1/spotify/search`

## Request

- Base URL: `https://api.captapi.com`
- URL: `https://api.captapi.com/v1/spotify/search`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Search Spotify — canonical spotify: URIs, explicit, fetchedAt (flat 2 credits).

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); a fallback path serves only on a miss — do not assume one raw schema across both (GraphQL __typename vs flat albumName/isExplicit). Envelope: query, type, fetchedAt, source (pathfinder; omitted when the fallback path served), 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; the fallback path scales per result (cost varies with results). Pass raw=true for per-result upstream payloads (omitted by default; searchTerm is not repeated inside raw).

Docs: https://captapi.com/apis/spotify-search

## Query parameters

- `q` string, required
- `type` string
- `limit` integer
- `raw` boolean
- `cache` boolean

## Response `200`

Success. The data object for this endpoint.

- object
  - `success` unknown, required
  - `data` object, required
    - `platform` string: Always "spotify" on this endpoint.
    - `query` string: Echo of the q parameter.
    - `type` string: Content type of the item.
    - `fetchedAt` string: When this search request completed (envelope only — not duplicated on results[]).
    - `totalReturned` integer: Number of items returned in this response.
    - `results` object[]
      - `platform` string: Always "spotify" on this endpoint.
      - `type` string: Content type of the item.
      - `uri` string: Canonical Spotify URI (spotify:track:… / album:… / artist:… / show:… / episode:…) — never a bare id.
      - `url` string: Canonical URL of the item.
      - `name` string: Result title (track, album, artist, or show name). Not a profile displayName alias.
      - `artists` object[]: On Pathfinder track/album hits: [{id, uri, name, url}]. The fallback path may still ship name strings.
        - `id` string: Id of this results item.
        - `uri` string: Canonical Spotify URI (spotify:track:… / album:… / artist:… / show:… / episode:…) — never a bare id.
        - `name` string: Result title (track, album, artist, or show name). Not a profile displayName alias.
        - `url` string: Canonical URL of the item.
      - `album` object: Album the track belongs to.
        - `id` string: Id of this results item.
        - `uri` string: Canonical Spotify URI (spotify:track:… / album:… / artist:… / show:… / episode:…) — never a bare id.
        - `name` string: Result title (track, album, artist, or show name). Not a profile displayName alias.
        - `url` string: Canonical URL of the item.
      - `durationMs` integer: Length in milliseconds.
      - `durationFormatted` string: Human duration (m:ss) when known.
      - `image` string: Image URL.
      - `id` string: Id of this results item.
      - `contentRating` string: Pathfinder contentRating.label when present on the search hydrate (NONE | EXPLICIT | NINETEEN_PLUS | UNKNOWN).
      - `explicit` boolean: Whether the item is marked explicit (from contentRating or the fallback path's isExplicit).
    - `source` unknown

## Other responses

- `400`: Bad request: wrong platform URL, unknown endpoint, or an invalid parameter value. Not billed.
- `401`: Missing, invalid or revoked API key. Not billed.
- `402`: Not enough credits for this request. Not billed.
- `404`: The resource does not exist or is not public. Not billed.
- `422`: A required parameter is missing or has the wrong type. Not billed.
- `429`: Rate limit reached. Wait for Retry-After seconds. Not billed.
- `502`: The platform could not be reached or returned nothing usable. Retryable, not billed. 503 and 504 use the same envelope.

---

[API](https://skmtc.dev/captapi/apis/captapi-api.md) · [All operations](https://skmtc.dev/captapi/apis/captapi-api/llms.txt) · [OpenAPI document](https://skmtc.dev/captapi/apis/captapi-api/revisions/c9b9ac5ff1bd?raw)