{ "openapi": "3.0.1", "info": { "title": "Spotify Scraper - Play Counts, Monthly Listeners & Playlists", "description": "Scrape Spotify tracks, albums, artists, playlists, podcasts and episodes by URL or search: play counts, monthly listeners, followers, world rank, top cities, label, track lists with streams, credits and concerts. Charts, one row per track, monitor mode. $2.80 per 1,000 rows. No login.", "version": "0.1", "x-build-id": "PI45bxN94sXDe3Anm" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/topapi~spotify-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-topapi-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/topapi~spotify-scraper/runs": { "post": { "operationId": "runs-sync-topapi-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/topapi~spotify-scraper/run-sync": { "post": { "operationId": "run-sync-topapi-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": { "urls": { "title": "Spotify URLs, URIs or IDs", "type": "array", "description": "Track, album, artist, playlist, podcast, episode or audiobook links, e.g. https://open.spotify.com/artist/0TnOYISbd1XYRBk9myaseg, spotify:track:4uLU6hMCjMI75M1A2tKUQC, a short link or a bare id.", "items": { "type": "string" } }, "searchTerms": { "title": "Search terms", "type": "array", "description": "Keywords to search on Spotify, e.g. \"lofi beats\", \"Taylor Swift\", \"true crime\". Each term is searched for every result type below.", "items": { "type": "string" } }, "searchType": { "title": "Search for", "type": "string", "description": "What kind of results a search term returns (songs when empty). Every result gets its full row (play counts, followers...); profiles carry name, username and picture." }, "searchTypes": { "title": "More result types", "type": "array", "description": "Search several result types at once, e.g. artists and playlists. Added to \"Search for\".", "items": { "type": "string", "enumSuggestedValues": [ "tracks", "artists", "albums", "playlists", "podcasts", "episodes", "audiobooks", "users" ], "enumTitles": [ "Songs (tracks)", "Artists", "Albums", "Playlists", "Podcasts (shows)", "Podcast episodes", "Audiobooks", "Profiles (users)" ] } }, "charts": { "title": "Spotify Charts", "type": "boolean", "description": "Add the current Spotify Charts (Weekly Top Songs, Top Albums and Top Artists, global, 50 each) with rank, previous and peak rank on every row.", "default": false }, "trackRows": { "title": "One row per track", "type": "boolean", "description": "Output one row per track (its play count) for every album, playlist, artist or track you give, instead of one row per album / playlist / artist. Charged per track row (see Pricing).", "default": false }, "idType": { "title": "Bare IDs are", "enum": [ "auto", "track", "album", "artist", "playlist", "show", "episode" ], "type": "string", "description": "What a bare 22-character id means. Links and spotify: URIs carry their own type and ignore this.", "default": "auto" }, "language": { "title": "Language", "type": "string", "description": "Language Spotify uses for search results and genre names, e.g. en, es, de, ja.", "default": "en" }, "searchLanguages": { "title": "Search in these languages too", "type": "array", "description": "Run every search again in these Spotify languages, on top of Language above. Each language returns partly different results (about 1 in 5 playlists were new per language in testing).", "items": { "type": "string", "enumSuggestedValues": [ "en", "es", "pt", "de", "fr", "it", "nl", "sv", "pl", "tr", "ja", "ko", "zh", "id", "hi", "ar" ] } }, "market": { "title": "Market (country)", "type": "string", "description": "Two-letter country code, e.g. US, GB, BR. Spotify reads the market from the IP address, so this is applied when the run uses an Apify proxy (see Advanced)." }, "minPlayCount": { "title": "Min play count", "minimum": 0, "type": "integer", "description": "Keep only tracks (and track rows) with at least this many plays, e.g. 1000000." }, "minMonthlyListeners": { "title": "Min monthly listeners", "minimum": 0, "type": "integer", "description": "Keep only artists with at least this many monthly listeners, e.g. 50000." }, "minFollowers": { "title": "Min followers / saves", "minimum": 0, "type": "integer", "description": "Keep only artists and playlists with at least this many followers (a playlist's saves), e.g. 200. Also accepted as minSaves." }, "excludeSpotifyOwned": { "title": "Skip Spotify-owned playlists", "type": "boolean", "description": "Leave out playlists run by Spotify itself (editorial, algorithmic and chart playlists), keeping those run by people and brands.", "default": false }, "excludePlaylistIds": { "title": "Skip these playlists", "type": "array", "description": "Playlist links or ids you already have, e.g. the id column of an earlier run. They are skipped.", "items": { "type": "string" } }, "includeTracks": { "title": "➕ Track lists", "type": "boolean", "description": "Albums and playlists carry their tracks with each track's play count; podcasts carry their episodes.", "default": true }, "maxTracksPerItem": { "title": "Max tracks per album / playlist", "minimum": 0, "maximum": 10000, "type": "integer", "description": "Tracks (or episodes) kept on each album, playlist or podcast row. 0 = all (Spotify playlists hold up to 10,000).", "default": 100 }, "includeDiscography": { "title": "Full artist discography", "type": "boolean", "description": "Artist rows carry every release (albums, singles, EPs, compilations) with date, label and track count, not just the latest 10 of each.", "default": false }, "followAlbums": { "title": "Follow artists' albums", "type": "boolean", "description": "For every artist (links, search results, chart artists), also return each of their albums as its own album row with per-track play counts. Counts toward Max results.", "default": false }, "followSingles": { "title": "Follow artists' singles", "type": "boolean", "description": "For every artist (links, search results, chart artists), also return each single and EP as its own album row with play counts. Counts toward Max results.", "default": false }, "followPopularReleases": { "title": "Follow popular releases", "type": "boolean", "description": "For every artist (links, search results, chart artists), also return Spotify's popular releases as album rows with play counts. Counts toward Max results.", "default": false }, "includeCredits": { "title": "Track credits", "type": "boolean", "description": "Every track row (One row per track too) carries its songwriting and production credits (writers, composers, producers, engineers, performers) and label source. One small request per track.", "default": false }, "scrapePreviewUrls": { "title": "30-second preview URLs", "type": "boolean", "description": "Add the 30-second MP3 preview link to tracks (from Spotify's embed player).", "default": true }, "includeConcerts": { "title": "Artist concerts", "type": "boolean", "description": "Artist rows carry their upcoming concerts (date, city, line-up). Charged as the concerts add-on per artist row that has concerts. Venue and tickets: turn on Concert details.", "default": false }, "enrichConcertDetails": { "title": "Concert details", "type": "boolean", "description": "With Artist concerts: add each concert's venue, country, coordinates, genres, and ticket sellers with links and availability (doors-open time when Spotify lists it). Included in the concerts add-on.", "default": false }, "concertDetailsLimit": { "title": "Max concerts with details", "minimum": 1, "maximum": 200, "type": "integer", "description": "How many concerts per artist get the details above.", "default": 20 }, "maxAlbumsPerArtist": { "title": "Albums per artist (track rows)", "minimum": 1, "maximum": 500, "type": "integer", "description": "With One row per track: how many of an artist's releases (newest first) are expanded into track rows.", "default": 3 }, "includeSingles": { "title": "Include singles (track rows)", "type": "boolean", "description": "With One row per track: count singles and EPs among an artist's releases.", "default": true }, "monitorMode": { "title": "🔁 Only new or changed", "type": "boolean", "description": "Return only rows that are new or whose play count, monthly listeners, followers, world rank, track count or playlist tracks changed since the last run, with the previous value and the difference.", "default": false }, "monitorStoreName": { "title": "Monitor memory name", "type": "string", "description": "Name of the key-value store that remembers the last values. Use a different name per schedule.", "default": "spotify-scraper-monitor" }, "maxResults": { "title": "Max results", "minimum": 0, "type": "integer", "description": "Most rows this run delivers (track rows with One row per track). 0 = no limit.", "default": 100 }, "maxResultsPerQuery": { "title": "Max results per search", "minimum": 0, "type": "integer", "description": "Most results per search term and result type. Spotify serves about 1,000 per search. 0 = as many as Spotify returns.", "default": 50 }, "compact": { "title": "Compact output", "type": "boolean", "description": "Core fields only (name, link, play count, listeners, followers...), sized for AI agents and MCP. Add-ons you turn on (concerts, credits, discography, raw) stay on the row.", "default": false }, "includeRaw": { "title": "Include raw Spotify data", "type": "boolean", "description": "Attach Spotify's full answer for each row under raw. Track rows from One row per track get Spotify's item for that track (the album or playlist entry).", "default": false }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Not needed: Spotify answers Apify's servers directly, and the run moves to the Apify proxy by itself if Spotify refuses. Set one to read another country's market.", "default": { "useApifyProxy": false } }, "maxConcurrency": { "title": "Parallel requests", "minimum": 1, "maximum": 12, "type": "integer", "description": "Requests in flight at once.", "default": 6 } } }, "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 }, "PROXY_UNBLOCKER_UNITS": { "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 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }