{
  "openapi": "3.0.1",
  "info": {
    "title": "Spotify Scraper - Monthly Listeners, Play Counts & Podcasts",
    "description": "Scrape Spotify artists, tracks, albums, playlists & podcasts — including monthly listeners, world rank, top cities, exact play counts, followers & artist contact leads. Data the official API hides. No API key, no login. Search or paste URLs, monitor stats over time.",
    "version": "0.1",
    "x-build-id": "krZKWUfh7UU1gehrk"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/scrapesage~spotify-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-scrapesage-spotify-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/scrapesage~spotify-scraper/runs": {
      "post": {
        "operationId": "runs-sync-scrapesage-spotify-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/scrapesage~spotify-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-scrapesage-spotify-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "searchQueries": {
            "title": "Search keywords",
            "type": "array",
            "description": "Things to search Spotify for — an artist, song, album, playlist or podcast name, e.g. <code>Taylor Swift</code>, <code>bohemian rhapsody</code>, <code>lofi beats</code>, <code>The Joe Rogan Experience</code>. Each query returns the chosen <b>Result type</b> below. Leave empty if you only paste URLs.",
            "items": {
              "type": "string"
            }
          },
          "searchType": {
            "title": "Result type (for keyword searches)",
            "enum": [
              "artist",
              "track",
              "album",
              "playlist",
              "podcast",
              "episode",
              "all"
            ],
            "type": "string",
            "description": "What kind of records keyword searches return. <b>Artist</b> = full profile with monthly listeners & play counts (the headline). <b>Track / Album / Playlist</b> = music records. <b>Podcast / Episode</b> = podcast shows & episodes. <b>All</b> mixes every type.",
            "default": "artist"
          },
          "startUrls": {
            "title": "Spotify URLs / URIs",
            "type": "array",
            "description": "Paste any Spotify links or URIs to scrape directly — artists (<code>open.spotify.com/artist/…</code>), tracks, albums, playlists, podcasts (<code>/show/…</code>) or episodes. <code>spotify:artist:…</code> URIs and <code>intl-xx</code> links work too. Used in addition to the search.",
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "market": {
            "title": "Market / country",
            "type": "string",
            "description": "Two-letter country code for availability, podcast catalogs and localized results, e.g. <code>US</code>, <code>GB</code>, <code>DE</code>, <code>BR</code>.",
            "default": "US"
          },
          "resultsPerSearch": {
            "title": "Results per search keyword",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "How many records to fetch for each keyword (capped by Max results overall).",
            "default": 20
          },
          "includeArtistDiscography": {
            "title": "Artists: include full discography",
            "type": "boolean",
            "description": "Add the artist's album/single/compilation list (title, type, year). Adds one request per artist. Counts are always included.",
            "default": false
          },
          "maxDiscographyItems": {
            "title": "Max discography items",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "Maximum releases to include when discography is on.",
            "default": 50
          },
          "includeRelatedArtists": {
            "title": "Artists: include related artists",
            "type": "boolean",
            "description": "Add up to 20 related/similar artists (name + id) for discovery and graph-building.",
            "default": false
          },
          "enrichArtistContacts": {
            "title": "Artists: enrich contact leads",
            "type": "boolean",
            "description": "Turn each artist into a B2B lead: when they list their own website, visit it (home + about/contact, max 3 pages) for publicly listed booking/management <b>emails</b>, phones and extra socials, then add a 0–100 lead score. Spotify never exposes emails — this is the only way to get them.",
            "default": false
          },
          "includeAlbumTracks": {
            "title": "Albums: include tracklist",
            "type": "boolean",
            "description": "Include each album's full tracklist with per-track play counts. Turn off for a lighter album record (label, copyrights, totals only).",
            "default": true
          },
          "maxTracksPerAlbum": {
            "title": "Max tracks per album",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "Cap the tracklist length per album.",
            "default": 50
          },
          "includePlaylistTracks": {
            "title": "Playlists: include tracklist",
            "type": "boolean",
            "description": "Include each playlist's tracks (track, artists, album). Turn off to only get name, owner, follower count & total tracks.",
            "default": true
          },
          "maxTracksPerPlaylist": {
            "title": "Max tracks per playlist",
            "minimum": 1,
            "maximum": 200,
            "type": "integer",
            "description": "Cap the number of tracks pulled per playlist.",
            "default": 100
          },
          "includeShowEpisodes": {
            "title": "Podcasts: include episodes",
            "type": "boolean",
            "description": "Include a page of a podcast show's episodes (title, description, duration, release date). Turn off for show metadata only.",
            "default": true
          },
          "maxEpisodesPerShow": {
            "title": "Max episodes per show",
            "minimum": 1,
            "maximum": 50,
            "type": "integer",
            "description": "Cap the number of episodes pulled per podcast show.",
            "default": 50
          },
          "maxResults": {
            "title": "Max results",
            "minimum": 1,
            "type": "integer",
            "description": "Maximum number of records to scrape across all searches and URLs.",
            "default": 100
          },
          "deduplicate": {
            "title": "Deduplicate records",
            "type": "boolean",
            "description": "Drop duplicate records that match more than one keyword/URL in the same run.",
            "default": true
          },
          "monitorMode": {
            "title": "Monitor mode (only new / changed)",
            "type": "boolean",
            "description": "Remember each record's key stat across runs in a named key-value store and emit ONLY records that are new or whose stats CHANGED (monthly listeners, play count, followers, episode count). Pair with Apify Schedules to track an artist's growth, a playlist's followers, or a podcast's new episodes over time — it complements the scheduler (the schedule starts the run, monitor mode dedupes against prior runs).",
            "default": false
          },
          "monitorKey": {
            "title": "Monitor key",
            "type": "string",
            "description": "Names the monitor's memory store so you can run several independent monitors (e.g. one per artist roster or playlist set). Reuse the same key to keep tracking the same feed.",
            "default": "default"
          },
          "maxConcurrency": {
            "title": "Max concurrency",
            "minimum": 1,
            "maximum": 8,
            "type": "integer",
            "description": "Parallel requests. Each uses a fresh proxy IP to spread Spotify's per-IP rate limit; keep this modest.",
            "default": 4
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Proxies to use. Datacenter (the default) is clean and cheap for Spotify's web back end; a fresh session per request spreads the per-IP rate limit.",
            "default": {
              "useApifyProxy": true
            }
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}