> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scraperize.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search

> Searches Apple Music (US storefront) by keyword, up to ~21 results per type as the web player shows them: top results, songs (with artists and album), albums, artists, playlists, stations, music videos and radio episodes — each with its id, name, subtitle, link, artwork and explicit flag. `type` returns one kind only (the other lists are empty). Only publicly available data is returned.

> [!NOTE]
>
> **Cost: 1 credit** per successful request. Errors and cache hits (`cache_max_age`) are free.

> [accordion] Copy for AI assistant
>
> Paste this into ChatGPT, Claude or your coding assistant to generate working code for this endpoint (use the copy button).
>
> ```text Prompt
> I want to make an API call to /v1/apple-music/search. Here are the details:
>
> Endpoint: GET https://api.scraperize.com/v1/apple-music/search
> Description: Searches Apple Music (US storefront) by keyword, up to ~21 results per type as the web player shows them: top results, songs (with artists and album), albums, artists, playlists, stations, music videos and radio episodes — each with its id, name, subtitle, link, artwork and explicit flag. `type` returns one kind only (the other lists are empty). Only publicly available data is returned.
>
> Required Headers:
> - x-api-key: Your API key
>
> Parameters:
> - query (string) [required]: What to search for.
> - type (select): What to return: `all` (default) or one kind.
> - cache_max_age (select): Optional. Return a cached result if one this age or newer exists — served for **0 credits** with `meta.cached=true` and `meta.cachedAt`. Otherwise a fresh scrape runs (**1 credit**) and refreshes the cache. Omit to always scrape fresh.
>
> Example Response:
> {
>   "data": {
>     "query": "taylor swift",
>     "type": "all",
>     "count": 137,
>     "topResults": [
>       {
>         "kind": "artist",
>         "id": "159260351",
>         "name": "Taylor Swift",
>         "headline": null,
>         "subtitle": "Artist",
>         "url": "https://music.apple.com/us/artist/taylor-swift/159260351",
>         "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/6d/67/88/6d67888b-9e7f-53af-7853-0f91d6fd2332/ami_U003aidentity_U003a994af5c375f4c3aa96cd6ced4a70…",
>         "isExplicit": false
>       }
>     ],
>     "songs": [
>       {
>         "id": "6814997425",
>         "name": "Patient Zero",
>         "url": "https://music.apple.com/us/album/patient-zero/6814997249?i=6814997425",
>         "albumId": "6814997249",
>         "albumName": null,
>         "releaseYear": null,
>         "artists": [
>           {
>             "id": "159260351",
>             "name": "Taylor Swift",
>             "url": "https://music.apple.com/us/artist/taylor-swift/159260351"
>           }
>         ],
>         "artistName": null,
>         "durationMs": null,
>         "trackNumber": null,
>         "discNumber": null,
>         "composer": null,
>         "previewUrl": null,
>         "isExplicit": false,
>         "isPopular": null,
>         "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/a0/dd/fd/a0ddfd72-ee9e-f046-6466-a5dbefc696fa/26UM1IM21436.rgb.jpg/3000x3000bb.jpg"
>       }
>     ],
>     "albums": [
>       {
>         "kind": "album",
>         "id": "6814997249",
>         "name": "The Life of a Showgirl: The Encore",
>         "headline": null,
>         "subtitle": "Taylor Swift",
>         "url": "https://music.apple.com/us/album/the-life-of-a-showgirl-the-encore/6814997249",
>         "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/a0/dd/fd/a0ddfd72-ee9e-f046-6466-a5dbefc696fa/26UM1IM21436.rgb.jpg/3000x3000bb.jpg",
>         "isExplicit": true
>       }
>     ],
>     "artists": [
>       {
>         "kind": "artist",
>         "id": "159260351",
>         "name": "Taylor Swift",
>         "headline": null,
>         "subtitle": null,
>         "url": "https://music.apple.com/us/artist/taylor-swift/159260351",
>         "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/6d/67/88/6d67888b-9e7f-53af-7853-0f91d6fd2332/ami_U003aidentity_U003a994af5c375f4c3aa96cd6ced4a70…",
>         "isExplicit": false
>       }
>     ],
>     "playlists": [
>       {
>         "kind": "playlist",
>         "id": "pl.3950454ced8c45a3b0cc693c2a7db97b",
>         "name": "Taylor Swift Essentials",
>         "headline": null,
>         "subtitle": "Apple Music Pop",
>         "url": "https://music.apple.com/us/playlist/taylor-swift-essentials/pl.3950454ced8c45a3b0cc693c2a7db97b",
>         "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/6d/67/88/6d67888b-9e7f-53af-7853-0f91d6fd2332/ami_U003aidentity_U003a994af5c375f4c3aa96cd6ced4a70…",
>         "isExplicit": false
>       }
>     ],
>     "stations": [
>       {
>         "kind": "station",
>         "id": "ra.a-159260351",
>         "name": "Taylor Swift",
>         "headline": null,
>         "subtitle": null,
>         "url": "https://music.apple.com/us/station/taylor-swift/ra.a-159260351",
>         "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/6d/67/88/6d67888b-9e7f-53af-7853-0f91d6fd2332/ami_U003aidentity_U003a994af5c375f4c3aa96cd6ced4a70…",
>         "isExplicit": false
>       }
>     ],
>     "musicVideos": [
>       {
>         "kind": "music-video",
>         "id": "1445005781",
>         "name": "Shake It Off",
>         "headline": null,
>         "subtitle": "Taylor Swift",
>         "url": "https://music.apple.com/us/music-video/shake-it-off/1445005781",
>         "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Video2/v4/02/e7/57/02e7574c-81f8-ed99-16ef-4156276fd41c/vidtrkimg_00843930013845_1_1.jpg/1920x1080bb.jpg",
>         "isExplicit": false
>       }
>     ],
>     "radioEpisodes": [
>       {
>         "kind": "radio-episode",
>         "id": "ra.1593740731",
>         "name": "Taylor Swift",
>         "headline": null,
>         "subtitle": "New Music Daily Radio",
>         "url": "https://music.apple.com/us/station/taylor-swift/ra.1593740731",
>         "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Features126/v4/21/bd/3a/21bd3a4a-47d1-9c24-1b3d-d01d38eaf3e8/U0MtTVMtV1ctRXAxMDAtVGF5bG9yU3dpZnQtUmFkaW8tQURBTV9JRD0xMD…",
>         "isExplicit": false
>       }
>     ],
>     "fetchedAt": "2026-11-10T16:02:31.760Z"
>   },
>   "meta": {
>     "requestId": "req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
>     "creditsCharged": 1,
>     "creditsRemaining": 4999,
>     "cached": false
>   }
> }
>
> Please help me write code in my preferred programming language to make this API call and handle the response appropriately. Include error handling and best practices.
> ```


## OpenAPI

````yaml /api-reference/openapi.json get /v1/apple-music/search
openapi: 3.0.3
info:
  title: Scraperize API
  version: 1.0.0
  description: >-
    Extract public data from social media platforms as clean JSON. Endpoints are
    split by platform and by what they return, e.g. `GET /v1/twitter/tweet`.


    ## Authentication

    Send your API key in the `x-api-key` header (or `Authorization: Bearer
    <key>`). Create keys in your dashboard.


    ## Credits

    Each successful live scrape costs **1 credit**. Credits are prepaid and
    never expire.


    ## Caching

    Every endpoint accepts an optional `cache_max_age`
    (`1d`|`3d`|`7d`|`14d`|`30d`). A cache hit within that window is returned for
    **0 credits**.


    ## Responses

    Success returns `{ "data": …, "meta": { "requestId", … } }`. Errors return
    `{ "error": { "code", "message", "requestId" } }` with a matching HTTP
    status. `meta` on a scrape carries `creditsCharged`, `creditsRemaining`,
    `cached`, and (on a hit) `cachedAt`.


    ## Rate limits

    Requests are limited per team per minute; over the limit returns `429` with
    a `Retry-After` header.
servers:
  - url: https://api.scraperize.com
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Twitter
    description: Twitter / X scraping endpoints
  - name: Facebook
    description: Facebook scraping endpoints
  - name: Linkme
    description: Linkme (link.me) scraping endpoints
  - name: Amazon
    description: Amazon (creator shop / storefront) scraping endpoints
  - name: Linkbio
    description: Linkbio (lnk.bio) scraping endpoints
  - name: Pillar
    description: Pillar (pillar.io) scraping endpoints
  - name: Komi
    description: Komi (komi.io) scraping endpoints
  - name: Linktree
    description: Linktree (linktr.ee) scraping endpoints
  - name: Kick
    description: Kick (kick.com) scraping endpoints
  - name: Snapchat
    description: Snapchat (snapchat.com) scraping endpoints
  - name: Telegram
    description: Telegram (t.me) scraping endpoints
  - name: LinkedIn
    description: LinkedIn scraping endpoints
  - name: Twitch
    description: Twitch scraping endpoints
  - name: TikTok
    description: TikTok (tiktok.com) scraping endpoints
  - name: Instagram
    description: Instagram scraping endpoints
  - name: Lagos Life
    description: Lagos Life scraping endpoints
  - name: Bluesky
    description: Bluesky (bsky.app) scraping endpoints
  - name: Threads
    description: Threads (threads.com) scraping endpoints
  - name: Reddit
    description: Reddit (reddit.com) scraping endpoints
  - name: Rumble
    description: Rumble (rumble.com) scraping endpoints
  - name: SoundCloud
    description: SoundCloud (soundcloud.com) scraping endpoints
  - name: Kwai
    description: Kwai (kwai.com) scraping endpoints
  - name: Apple Music
    description: Apple Music (music.apple.com) scraping endpoints
  - name: Truth Social
    description: Truth Social (truthsocial.com) scraping endpoints
  - name: YouTube
    description: YouTube (youtube.com) scraping endpoints
paths:
  /v1/apple-music/search:
    get:
      tags:
        - Apple Music
      summary: Search
      description: >-
        Searches Apple Music (US storefront) by keyword, up to ~21 results per
        type as the web player shows them: top results, songs (with artists and
        album), albums, artists, playlists, stations, music videos and radio
        episodes — each with its id, name, subtitle, link, artwork and explicit
        flag. `type` returns one kind only (the other lists are empty). Only
        publicly available data is returned.
      parameters:
        - name: query
          in: query
          required: true
          description: What to search for.
          schema:
            type: string
          example: taylor swift
        - name: type
          in: query
          required: false
          description: 'What to return: `all` (default) or one kind.'
          schema:
            type: string
            enum:
              - all
              - song
              - album
              - artist
              - playlist
              - station
              - music-video
              - radio-episode
            default: all
        - name: cache_max_age
          in: query
          required: false
          description: >-
            Optional. Return a cached result if one this age or newer exists —
            served for **0 credits** with `meta.cached=true` and
            `meta.cachedAt`. Otherwise a fresh scrape runs (**1 credit**) and
            refreshes the cache. Omit to always scrape fresh.
          schema:
            type: string
            enum:
              - 1d
              - 3d
              - 7d
              - 14d
              - 30d
          example: 7d
      responses:
        '200':
          description: The results (empty lists when nothing matches).
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                  meta:
                    type: object
                    description: >-
                      requestId + credit/caching metadata (creditsCharged,
                      creditsRemaining, cached, cachedAt).
                required:
                  - data
                  - meta
              example:
                data:
                  query: taylor swift
                  type: all
                  count: 137
                  topResults:
                    - kind: artist
                      id: '159260351'
                      name: Taylor Swift
                      headline: null
                      subtitle: Artist
                      url: https://music.apple.com/us/artist/taylor-swift/159260351
                      artworkUrl: >-
                        https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/6d/67/88/6d67888b-9e7f-53af-7853-0f91d6fd2332/ami_U003aidentity_U003a994af5c375f4c3aa96cd6ced4a700799-2026-09-25T04-00-05.358Z_cropped.png/1640x1640bb.jpg
                      isExplicit: false
                    - kind: album
                      id: '6814997249'
                      name: 'The Life of a Showgirl: The Encore'
                      headline: null
                      subtitle: Album · Taylor Swift
                      url: >-
                        https://music.apple.com/us/album/the-life-of-a-showgirl-the-encore/6814997249
                      artworkUrl: >-
                        https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/a0/dd/fd/a0ddfd72-ee9e-f046-6466-a5dbefc696fa/26UM1IM21436.rgb.jpg/3000x3000bb.jpg
                      isExplicit: true
                    - kind: song
                      id: '6814997425'
                      name: Patient Zero
                      headline: null
                      subtitle: Song · Taylor Swift
                      url: >-
                        https://music.apple.com/us/album/patient-zero/6814997249?i=6814997425
                      artworkUrl: >-
                        https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/a0/dd/fd/a0ddfd72-ee9e-f046-6466-a5dbefc696fa/26UM1IM21436.rgb.jpg/3000x3000bb.jpg
                      isExplicit: false
                  songs:
                    - id: '6814997425'
                      name: Patient Zero
                      url: >-
                        https://music.apple.com/us/album/patient-zero/6814997249?i=6814997425
                      albumId: '6814997249'
                      albumName: null
                      releaseYear: null
                      artists:
                        - id: '159260351'
                          name: Taylor Swift
                          url: >-
                            https://music.apple.com/us/artist/taylor-swift/159260351
                      artistName: null
                      durationMs: null
                      trackNumber: null
                      discNumber: null
                      composer: null
                      previewUrl: null
                      isExplicit: false
                      isPopular: null
                      artworkUrl: >-
                        https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/a0/dd/fd/a0ddfd72-ee9e-f046-6466-a5dbefc696fa/26UM1IM21436.rgb.jpg/3000x3000bb.jpg
                    - id: '1833328840'
                      name: The Fate of Ophelia
                      url: >-
                        https://music.apple.com/us/album/the-fate-of-ophelia/1833328839?i=1833328840
                      albumId: '1833328839'
                      albumName: null
                      releaseYear: null
                      artists:
                        - id: '159260351'
                          name: Taylor Swift
                          url: >-
                            https://music.apple.com/us/artist/taylor-swift/159260351
                      artistName: null
                      durationMs: null
                      trackNumber: null
                      discNumber: null
                      composer: null
                      previewUrl: null
                      isExplicit: false
                      isPopular: null
                      artworkUrl: >-
                        https://is1-ssl.mzstatic.com/image/thumb/Music211/v4/2d/46/e0/2d46e0bc-8ab9-85dd-4b56-ee6951351034/25UM1IM19577.rgb.jpg/3000x3000bb.jpg
                    - id: '6775527443'
                      name: I Knew It, I Knew You (From "Toy Story 5")
                      url: >-
                        https://music.apple.com/us/album/i-knew-it-i-knew-you-from-toy-story-5/6775527442?i=6775527443
                      albumId: '6775527442'
                      albumName: null
                      releaseYear: null
                      artists:
                        - id: '159260351'
                          name: Taylor Swift
                          url: >-
                            https://music.apple.com/us/artist/taylor-swift/159260351
                      artistName: null
                      durationMs: null
                      trackNumber: null
                      discNumber: null
                      composer: null
                      previewUrl: null
                      isExplicit: false
                      isPopular: null
                      artworkUrl: >-
                        https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/34/35/6c/34356cb4-bd0b-3bac-b118-1a6d7264dc64/26UMGIM69942.rgb.jpg/3000x3000bb.jpg
                  albums:
                    - kind: album
                      id: '6814997249'
                      name: 'The Life of a Showgirl: The Encore'
                      headline: null
                      subtitle: Taylor Swift
                      url: >-
                        https://music.apple.com/us/album/the-life-of-a-showgirl-the-encore/6814997249
                      artworkUrl: >-
                        https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/a0/dd/fd/a0ddfd72-ee9e-f046-6466-a5dbefc696fa/26UM1IM21436.rgb.jpg/3000x3000bb.jpg
                      isExplicit: true
                    - kind: album
                      id: '1742057774'
                      name: 'THE TORTURED POETS DEPARTMENT: THE ANTHOLOGY'
                      headline: null
                      subtitle: Taylor Swift
                      url: >-
                        https://music.apple.com/us/album/the-tortured-poets-department-the-anthology/1742057774
                      artworkUrl: >-
                        https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/a4/86/59/a486593a-53c9-1c2a-5122-8f25339f7359/24UMGIM44778.rgb.jpg/3000x3000bb.jpg
                      isExplicit: true
                    - kind: album
                      id: '1528112358'
                      name: folklore (deluxe version)
                      headline: null
                      subtitle: Taylor Swift
                      url: >-
                        https://music.apple.com/us/album/folklore-deluxe-version/1528112358
                      artworkUrl: >-
                        https://is1-ssl.mzstatic.com/image/thumb/Music115/v4/b5/80/dc/b580dca0-349d-036b-e09b-bd849f6affd8/20UMGIM64216.rgb.jpg/3000x3000bb.jpg
                      isExplicit: true
                  artists:
                    - kind: artist
                      id: '159260351'
                      name: Taylor Swift
                      headline: null
                      subtitle: null
                      url: https://music.apple.com/us/artist/taylor-swift/159260351
                      artworkUrl: >-
                        https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/6d/67/88/6d67888b-9e7f-53af-7853-0f91d6fd2332/ami_U003aidentity_U003a994af5c375f4c3aa96cd6ced4a700799-2026-09-25T04-00-05.358Z_cropped.png/1640x1640bb.jpg
                      isExplicit: false
                    - kind: artist
                      id: '400555769'
                      name: Natalie Taylor
                      headline: null
                      subtitle: null
                      url: >-
                        https://music.apple.com/us/artist/natalie-taylor/400555769
                      artworkUrl: >-
                        https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages211/v4/b5/3e/c7/b53ec778-048f-4f07-17aa-cd19468adf62/0aef0deb-fee7-4bfa-bab5-914d9fa38045_file_cropped.png/1122x1122bb.jpg
                      isExplicit: false
                    - kind: artist
                      id: '1865952014'
                      name: Taylor Swift Tribute Songs
                      headline: null
                      subtitle: null
                      url: >-
                        https://music.apple.com/us/artist/taylor-swift-tribute-songs/1865952014
                      artworkUrl: >-
                        https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/f3/69/70/f3697002-0508-7d32-bb03-77753e781162/artwork.jpg/3000x3000ac.jpg
                      isExplicit: false
                  playlists:
                    - kind: playlist
                      id: pl.3950454ced8c45a3b0cc693c2a7db97b
                      name: Taylor Swift Essentials
                      headline: null
                      subtitle: Apple Music Pop
                      url: >-
                        https://music.apple.com/us/playlist/taylor-swift-essentials/pl.3950454ced8c45a3b0cc693c2a7db97b
                      artworkUrl: >-
                        https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/6d/67/88/6d67888b-9e7f-53af-7853-0f91d6fd2332/ami_U003aidentity_U003a994af5c375f4c3aa96cd6ced4a700799-2026-09-25T04-00-05.358Z_cropped.png/1080x1080SC.FPESS05.jpg?l=en-US
                      isExplicit: false
                    - kind: playlist
                      id: pl.57891bdd1bc840948374f1c4cbe9c840
                      name: Taylor Swift’s Eras Tour Set List
                      headline: null
                      subtitle: Apple Music Pop
                      url: >-
                        https://music.apple.com/us/playlist/taylor-swifts-eras-tour-set-list/pl.57891bdd1bc840948374f1c4cbe9c840
                      artworkUrl: >-
                        https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/6d/67/88/6d67888b-9e7f-53af-7853-0f91d6fd2332/ami_U003aidentity_U003a994af5c375f4c3aa96cd6ced4a700799-2026-09-25T04-00-05.358Z_cropped.png/1080x1080SC.FPSL03.jpg?l=en-US
                      isExplicit: false
                    - kind: playlist
                      id: pl.455d78fed003473787886679c686fdcd
                      name: Am I Allowed to Cry? Songs
                      headline: null
                      subtitle: Apple Music
                      url: >-
                        https://music.apple.com/us/playlist/am-i-allowed-to-cry-songs/pl.455d78fed003473787886679c686fdcd
                      artworkUrl: >-
                        https://is1-ssl.mzstatic.com/image/thumb/Features221/v4/38/a7/da/38a7da79-1149-c368-bbe4-de472dc9b5e0/9f77923b-b8a7-4521-b821-50e58ff357b5.png/1080x1080SC.DN02.jpg?l=en-US
                      isExplicit: false
                  stations:
                    - kind: station
                      id: ra.a-159260351
                      name: Taylor Swift
                      headline: null
                      subtitle: null
                      url: >-
                        https://music.apple.com/us/station/taylor-swift/ra.a-159260351
                      artworkUrl: >-
                        https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/6d/67/88/6d67888b-9e7f-53af-7853-0f91d6fd2332/ami_U003aidentity_U003a994af5c375f4c3aa96cd6ced4a700799-2026-09-25T04-00-05.358Z_cropped.png/1640x1640AM.RSAB04.jpg
                      isExplicit: false
                    - kind: station
                      id: ra.1542659588
                      name: 'Taylor Swift: Apple Music Awards 2020 Day 2'
                      headline: null
                      subtitle: >-
                        Tune in to see Taylor Swift on the Apple Music Awards on
                        December 15 at 5 pm PT.
                      url: >-
                        https://music.apple.com/us/station/taylor-swift-apple-music-awards-2020-day-2/ra.1542659588
                      artworkUrl: >-
                        https://is1-ssl.mzstatic.com/image/thumb/Features114/v4/4b/2f/c8/4b2fc809-3fc8-d07b-3f71-9fce6f9bdb7f/U0MtTVQtV1ctSExTLUp1c3QgZm9yIFRheWxvci5wbmc.png/4320x1080sr.jpg
                      isExplicit: false
                    - kind: station
                      id: ra.1874948486
                      name: Taylor Swift Radio
                      headline: null
                      subtitle: null
                      url: >-
                        https://music.apple.com/us/station/taylor-swift-radio/ra.1874948486
                      artworkUrl: >-
                        https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/1f/e4/a8/1fe4a834-8f8d-844d-ce1e-b2eb6efe0d12/WorldDetails17515411564227545544.png/600x338bb.jpg
                      isExplicit: false
                  musicVideos:
                    - kind: music-video
                      id: '1445005781'
                      name: Shake It Off
                      headline: null
                      subtitle: Taylor Swift
                      url: >-
                        https://music.apple.com/us/music-video/shake-it-off/1445005781
                      artworkUrl: >-
                        https://is1-ssl.mzstatic.com/image/thumb/Video2/v4/02/e7/57/02e7574c-81f8-ed99-16ef-4156276fd41c/vidtrkimg_00843930013845_1_1.jpg/1920x1080bb.jpg
                      isExplicit: false
                    - kind: music-video
                      id: '1468647174'
                      name: You Need To Calm Down
                      headline: null
                      subtitle: Taylor Swift
                      url: >-
                        https://music.apple.com/us/music-video/you-need-to-calm-down/1468647174
                      artworkUrl: >-
                        https://is1-ssl.mzstatic.com/image/thumb/Video123/v4/1b/64/29/1b64297a-b315-fbe4-61a9-a841a93548c0/19UMGIM53855.crop.jpg/1912x1072bb.jpg
                      isExplicit: false
                    - kind: music-video
                      id: '6816241368'
                      name: Patient Zero
                      headline: null
                      subtitle: Taylor Swift
                      url: >-
                        https://music.apple.com/us/music-video/patient-zero/6816241368
                      artworkUrl: >-
                        https://is1-ssl.mzstatic.com/image/thumb/Video221/v4/02/21/39/022139aa-083d-21c1-f0b9-cb7dc630dc98/26UM1IM22083.crop.jpg/3701x1912bb.jpg
                      isExplicit: false
                  radioEpisodes:
                    - kind: radio-episode
                      id: ra.1593740731
                      name: Taylor Swift
                      headline: null
                      subtitle: New Music Daily Radio
                      url: >-
                        https://music.apple.com/us/station/taylor-swift/ra.1593740731
                      artworkUrl: >-
                        https://is1-ssl.mzstatic.com/image/thumb/Features126/v4/21/bd/3a/21bd3a4a-47d1-9c24-1b3d-d01d38eaf3e8/U0MtTVMtV1ctRXAxMDAtVGF5bG9yU3dpZnQtUmFkaW8tQURBTV9JRD0xMDUzMTY1ODU3LnBuZw.png/4320x1080sr.jpg
                      isExplicit: false
                    - kind: radio-episode
                      id: ra.1649631546
                      name: Taylor Swift
                      headline: null
                      subtitle: New Music Daily Radio
                      url: >-
                        https://music.apple.com/us/station/taylor-swift/ra.1649631546
                      artworkUrl: >-
                        https://is1-ssl.mzstatic.com/image/thumb/Features112/v4/82/f1/22/82f12210-8a57-1a89-c407-8fb75408bc9b/453721ab-6294-4e9e-83ca-f5e4bb34fb70.png/4320x1080sr.jpg
                      isExplicit: false
                    - kind: radio-episode
                      id: ra.1738080111
                      name: Taylor Swift
                      headline: null
                      subtitle: New Music Daily Radio
                      url: >-
                        https://music.apple.com/us/station/taylor-swift/ra.1738080111
                      artworkUrl: >-
                        https://is1-ssl.mzstatic.com/image/thumb/Features/v4/68/4c/ac/684cac44-ae08-3d11-a73d-135ab063e5fa/cc75276d-6e0c-4d53-a138-6f8298d51931.png/4320x1080sr.jpg
                      isExplicit: false
                  fetchedAt: '2026-11-10T16:02:31.760Z'
                meta:
                  requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
                  creditsCharged: 1
                  creditsRemaining: 4999
                  cached: false
        '401':
          description: Missing, invalid, or revoked API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: UNAUTHORIZED
                  message: API key required — pass it in the `x-api-key` header.
                  requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
        '402':
          description: Not enough credits for this request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: INSUFFICIENT_CREDITS
                  message: >-
                    This request costs 1 credit, but your balance is 0. Top up
                    to continue.
                  requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
        '422':
          description: >-
            Invalid query parameters (`query` is required; `type` must be one of
            the listed values).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: Request validation failed
                  requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
                  details:
                    - path: url
                      message: url is required
        '429':
          description: Over the per-minute rate limit — honour `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: RATE_LIMITED
                  message: >-
                    Rate limit exceeded — max 100 requests per 60s. Retry in
                    ~30s.
                  requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
        '503':
          description: >-
            Temporarily unavailable — retry after `Retry-After`. `error.code`
            tells you why: `UPSTREAM_BLOCKED` (the source blocked this request),
            `EXTRACTION_FAILED` (the source returned unexpected data),
            `PLATFORM_UNAVAILABLE` (the source is down), or
            `SERVICE_UNAVAILABLE` (we are at capacity).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: UPSTREAM_BLOCKED
                  message: >-
                    The source is temporarily unavailable. Please try again
                    shortly.
                  requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: NOT_FOUND
            message:
              type: string
              example: The requested content was not found.
            requestId:
              type: string
              example: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
            details:
              type: array
              items:
                type: object
              description: Present on validation errors.
          required:
            - code
            - message
            - requestId
      required:
        - error
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Your API key. Send it in the `x-api-key` header (or `Authorization:
        Bearer <key>`). Create and manage keys from your dashboard.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.