# Spotify Scraper ✨ (`apiharvest/spotify-scraper`) Actor Search tracks, albums, artists, playlists, genres, audiobooks, podcasts & episodes β€” multiple keywords per run. Fetch full metadata by URI/URL: track lists, chapters, episode counts, follower stats, popularity scores, release dates & cover images. No Spotify account required πŸ” Spotify Scraper✨ - **URL**: https://apify.com/apiharvest/spotify-scraper.md - **Developed by:** [APIHarvest](https://apify.com/apiharvest) (community) - **Categories:** Developer tools, Social media, Automation - **Stats:** 6 total users, 1 monthly users, 91.4% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $2.00 / 1,000 result scrapeds This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README --- ## Spotify Scraper ✨ --- The most powerful **Spotify Scraper** and **Spotify Search** actor on Apify. Search any keyword across every Spotify category β€” or paste URIs/URLs to fetch complete metadata for any track, album, artist, playlist, genre, audiobook, podcast, or episode. This **Spotify Scraper** extracts everything Spotify has: full track details, album track lists, artist overviews, playlist contents, genre/mood browsing, audiobook chapters, podcast episodes, and more β€” all without needing a Spotify account or premium subscription. ### Why Choose This Spotify Scraper? Most Spotify scrapers only handle one data type or break when Spotify updates its platform. This **Spotify Scraper** supports **9 different data categories** across **2 powerful modes**, with automatic retry logic, residential proxy optimization for 55+ countries, and clean JSON output ready for analysis. | Feature | This Spotify Scraper | Other Spotify Scrapers | |---|---|---| | Search across 9 categories | βœ… Tracks, Albums, Artists, Playlists, Genres, Users, Audiobooks, Episodes, Podcasts | ⚠️ 1–3 types at best | | Full detail fetching by URI/URL | βœ… Paste any Spotify URI or URL into Spotify Scraper | ❌ Search-only or limited | | Combined Search + Detail mode | βœ… Auto-fetch details for every search result using Spotify Scraper | ❌ Not available | | Playlist & album track lists | βœ… Full paginated track lists extracted by Spotify Scraper | ⚠️ First page only | | Genre/Mood browsing with sections | βœ… Complete section data with item details via Spotify Scraper | ❌ Not supported | | Audiobook chapter lists | βœ… Full chapter pagination with Spotify Scraper | ❌ Not supported | | Podcast episode lists | βœ… Full episode pagination with Spotify Scraper | ❌ Not supported | | Artist overview (bio, stats, discography) | βœ… Complete overview data scraped by Spotify Scraper | ⚠️ Basic info only | | 55+ proxy countries | βœ… US, GB, AU, CA + 51 more | ⚠️ No proxy or limited | | No browser required | βœ… Pure HTTP (fast & cheap) | ❌ Most use Puppeteer | | Automatic retry on empty results | βœ… Built-in retry logic in Spotify Scraper | ❌ Fails silently | | Clean flat JSON output | βœ… Ready for analysis | ⚠️ Nested/raw API dumps | This **Spotify Scraper** delivers more Spotify data at a fraction of the cost compared to every alternative Spotify Scraper available. --- ### ✨ Key Features of Spotify Scraper #### πŸ” Spotify Scraper β€” Search Mode Features - **Spotify Scraper** search across **9 categories**: Tracks, Albums, Artists, Playlists, Genres/Moods, Users/Profiles, Audiobooks, Full Episodes, Podcasts/Shows - Customizable result limits, offsets, and top-results count per search type in **Spotify Scraper** - Optional **Fetch Full Details** toggle in **Spotify Scraper** β€” automatically runs the matching detail scraper on every search result - Keyword-based search returns ranked results just like the official Spotify app using **Spotify Scraper** #### πŸ”— Spotify Scraper β€” Get Details Mode Features - Paste one or more Spotify URIs or open.spotify.com URLs into **Spotify Scraper** - This **Spotify Scraper** fetches complete metadata for each entity: - 🎡 **Tracks**: Full track metadata, artists, album info, duration, popularity, preview URLs via **Spotify Scraper** - πŸ’Ώ **Albums**: Album metadata + paginated track list with offset/limit control via **Spotify Scraper** - 🎀 **Artists**: Complete artist overview β€” bio, stats, top tracks, discography, related artists, playlists via **Spotify Scraper** - 🎧 **Playlists**: Playlist metadata + paginated track list with offset/limit control via **Spotify Scraper** - 🎨 **Genres/Moods**: Genre/mood page browsing with section navigation and item details via **Spotify Scraper** - πŸ“š **Audiobooks**: Metadata + chapter list + optional similar audiobook recommendations via **Spotify Scraper** - πŸŽ™οΈ **Full Episodes**: Episode metadata + optional recommended episodes via **Spotify Scraper** - πŸŽ™ **Podcasts/Shows**: Show metadata + paginated episode list + optional recommended shows via **Spotify Scraper** #### 🌐 Proxy & Regional Support in Spotify Scraper - **55+ residential proxy countries** β€” **Spotify Scraper** routes requests through your chosen location - ⭐ **US recommended** β€” widest catalog, only country guaranteed for ALL **Spotify Scraper** search types - Regional restrictions handled automatically by **Spotify Scraper**: - Podcasts & Episodes β†’ US, GB, AU, or CA - Audiobooks β†’ US, GB, AU, CA only - Music (Tracks/Albums/Artists) β†’ works in most countries --- ### 🎯 Two Powerful Modes in Spotify Scraper #### Mode 1: πŸ” Search Mode β€” Spotify Scraper by Keyword(s) Enter one or more keywords and select a search type. This **Spotify Scraper** search mode sends each keyword to Spotify and returns ranked results. Available search types in **Spotify Scraper**: | Search Type | What This Spotify Scraper Returns | |---|---| | 🎡 Tracks / Songs | Track name, artist(s), album, duration, popularity, URI, preview URL | | πŸ’Ώ Albums | Album name, artist(s), release date, total tracks, cover art, URI | | 🎀 Artists | Artist name, genres, follower count, popularity, image, URI | | 🎧 Playlists | Playlist name, owner, description, track count, cover image, URI | | 🎨 Genres / Moods | Genre pages, mood categories with playlists and curated content | | πŸ‘€ Users / Profiles | Username, display name, follower count, image, profile URI | | πŸ“š Audiobooks | Title, author(s), narrator(s), publisher, description, chapter count, URI | | πŸŽ™οΈ Full Episodes | Episode title, show name, description, duration, release date, URI | | πŸŽ™ Podcasts / Shows | Show name, publisher, description, total episodes, URI | **Fetch Full Details** β€” Every search type in **Spotify Scraper** (except Users) has a toggle to automatically run the matching detail **Spotify Scraper** on every result URI. Turn it ON to get complete metadata merged into each search result. #### Mode 2: πŸ”— Get Details Mode β€” Spotify Scraper by URI/URL Paste one or more Spotify URIs or URLs, select the entity type, and this **Spotify Scraper** fetches complete metadata for each item. | Get Details Type | What This Spotify Scraper Returns | |---|---| | 🎡 Track | Complete track metadata β€” artists, album, duration, popularity, preview URL, disc/track number | | πŸ’Ώ Album | Full album metadata + paginated track list (control offset & limit) | | 🎀 Artist | Complete artist overview β€” biography, stats, top tracks, albums, singles, compilations, related artists, playlists | | 🎧 Playlist | Full playlist metadata + paginated track list (control offset & limit) | | 🎨 Genre / Mood | Genre page with sections β€” each section contains curated playlists and content | | πŸ“š Audiobook | Metadata + chapter list (paginated) + optional similar audiobooks | | πŸŽ™οΈ Full Episode | Episode details + optional recommended episodes | | πŸŽ™ Podcast / Show | Show metadata + episode list (paginated) + optional recommended shows | --- ### πŸ”— Supported Spotify URL & URI Formats in Spotify Scraper This **Spotify Scraper** accepts all standard Spotify identifiers in Get Details Mode: #### Spotify URI Format | Entity | URI Format | Example | |---|---|---| | Track | `spotify:track:ID` | `spotify:track:0VjIjW4GlUZAMYd2vXMi3b` | | Album | `spotify:album:ID` | `spotify:album:1DFixLWuPkv3KT3TnV35m3` | | Artist | `spotify:artist:ID` | `spotify:artist:06HL4z0CvFAxyc27GXpf02` | | Playlist | `spotify:playlist:ID` | `spotify:playlist:37i9dQZF1DXcBWIGoYBM5M` | | Genre / Mood | `spotify:genre:ID` or `spotify:page:ID` | `spotify:genre:0JQ5DAqbMKFEC4WFtoNRpw` | | Audiobook | `spotify:show:ID` (select πŸ“š Audiobook) | `spotify:show:5CfCWKI5pZ28U0uOzXkDHe` | | Episode | `spotify:episode:ID` | `spotify:episode:512ojhOuo1ktJprKbVcKyQ` | | Podcast / Show | `spotify:show:ID` (select πŸŽ™ Podcast) | `spotify:show:4rOoJ6Egrf8K2IrywzwOMk` | #### open.spotify.com URL Format | Entity | URL Format | |---|---| | Track | `https://open.spotify.com/track/ID` | | Album | `https://open.spotify.com/album/ID` | | Artist | `https://open.spotify.com/artist/ID` | | Playlist | `https://open.spotify.com/playlist/ID` | | Genre / Mood | `https://open.spotify.com/genre/ID` | | Episode | `https://open.spotify.com/episode/ID` | | Podcast / Show | `https://open.spotify.com/show/ID` | > πŸ’‘ **Tip**: For `spotify:show:` URIs, select the correct type in **Spotify Scraper** (πŸ“š Audiobook or πŸŽ™ Podcast/Show) so the right **Spotify Scraper** operations run. --- ### πŸš€ Quick Start Examples for Spotify Scraper #### Example 1: Spotify Scraper Search for Tracks ```json { "mode": "search", "searchType": "searchTracks", "keyword": ["Blinding Lights"], "tracks_search_limit": 10, "proxyCountry": "US" } ```` This **Spotify Scraper** search returns up to 10 track results for "Blinding Lights". #### Example 2: Spotify Scraper β€” Get Full Album Details ```json { "mode": "get_details", "getDetailsType": "album", "spotifyUris": ["spotify:album:4yP0hdKOZPNshxUOjY0cZj"], "albums_get_limit": 100, "proxyCountry": "US" } ``` This **Spotify Scraper** fetches complete album metadata plus up to 100 tracks from the album's track list. #### Example 3: Spotify Scraper β€” Search + Auto-Fetch Artist Details ```json { "mode": "search", "searchType": "searchArtists", "keyword": ["The Weeknd"], "artists_search_limit": 5, "artists_fetchDetails": true, "proxyCountry": "US" } ``` This **Spotify Scraper** finds up to 5 artists, then automatically fetches complete artist overviews for each result. *** ### πŸ“¦ Output Format of Spotify Scraper This **Spotify Scraper** outputs clean, flat JSON objects to the Apify dataset: - `scraper_type` β€” which **Spotify Scraper** type was used - `keyword` or `uri` β€” input processed by **Spotify Scraper** - `result` β€” complete Spotify data object extracted by **Spotify Scraper** *** ### ❓ FAQ β€” Spotify Scraper **Q: Do I need a Spotify account to use this Spotify Scraper?**\ A: No. This **Spotify Scraper** works without any Spotify account or API credentials. **Q: Can I search and get details in the same run with Spotify Scraper?**\ A: Yes! In Search Mode, turn on the **Fetch Full Details** toggle in **Spotify Scraper**. **Q: Why are my results empty in Spotify Scraper?**\ A: Try switching the proxy country to **US** in **Spotify Scraper**. **Q: Can I paste both URIs and URLs into Spotify Scraper?**\ A: Yes. This **Spotify Scraper** accepts both URI and open.spotify.com URL formats. # Actor input Schema ## `mode` (type: `string`): Choose how to scrape Spotify: πŸ” Search Mode β€” enter a keyword and pick a Search Type. Returns ranked results. Active fields: Search Type, Search Keyword, and each type's filter section below. πŸ”— Get Details Mode β€” paste Spotify URIs/URLs and pick a Get Details Type. Returns full metadata. Active fields: Get Details Type, Spotify URIs / URLs, and each type's filter section below. ## `searchType` (type: `string`): ⚠️ Search Mode only β€” ignored in Get Details Mode. Which Spotify category to search by keyword. 🎡 Tracks Β· πŸ’Ώ Albums Β· 🎀 Artists Β· 🎧 Playlists Β· 🎨 Genres/Moods Β· πŸ‘€ Users Β· πŸ“š Audiobooks Β· πŸŽ™οΈ Full Episodes Β· πŸŽ™ Podcasts/Shows πŸ’‘ Each type also has a 'Fetch Full Details' toggle inside its own section below β€” turn it on to automatically run the matching get-detail scraper on every result URI found. ## `keyword` (type: `array`): ⚠️ Search Mode only β€” ignored in Get Details Mode. One or more search terms sent to Spotify. Each keyword runs as a separate search. Use full track names, artist names, or titles for accurate results. πŸ’‘ Add multiple keywords β€” one per entry β€” to search for several terms in a single run. ## `getDetailsType` (type: `string`): ⚠️ Get Details Mode only β€” ignored in Search Mode. Select which Spotify entity type you are fetching. This must match the URIs you paste below. 🎡 Track Β· πŸ’Ώ Album Β· 🎀 Artist Β· 🎧 Playlist Β· 🎨 Genre/Mood Β· πŸ“š Audiobook Β· πŸŽ™ Podcast/Show Β· πŸŽ™οΈ Full Episode πŸ’‘ For spotify:show: URIs β€” select Audiobook or Podcast/Show explicitly since both share the same URI prefix. ## `spotifyUris` (type: `array`): ⚠️ Get Details Mode only β€” ignored in Search Mode. One or more Spotify URIs or open.spotify.com URLs to fetch. Examples: spotify:track:ID Β· https://open.spotify.com/album/ID πŸ’‘ All URIs must be the same entity type β€” select the matching type in Get Details Type above. ## `showDetailType` (type: `string`): ⚠️ This field is no longer needed. Use Get Details Type above to select Audiobook or Podcast/Show explicitly. Kept for backward compatibility only. Ignored when Get Details Type is set. ## `proxyCountry` (type: `string`): Residential proxy exit country β€” Spotify sees your requests as coming from this location. ⭐ US recommended β€” widest catalog, only country guaranteed for ALL scraper types (Tracks, Albums, Artists, Playlists, Audiobooks, Podcasts, Episodes). ⚠️ Regional restrictions: β€’ Podcasts & Episodes β†’ require US, GB, AU, or CA β€’ Audiobooks β†’ US, GB, AU, CA only β€’ Music (Tracks/Albums/Artists) β†’ works in most countries If results are empty, switch to US. If US still returns empty, it's a script or API issue β€” contact the developer. ## `tracks_search_offset` (type: `integer`): Starting position for search pagination. 0 = first page. πŸ“Œ Search Mode only β€” ignored in Get Details Mode. ## `tracks_search_limit` (type: `integer`): Maximum number of track results to return. πŸ“Œ Search Mode only β€” ignored in Get Details Mode. ## `tracks_search_numberOfTopResults` (type: `integer`): Number of top-ranked items highlighted in the response. πŸ“Œ Search Mode only β€” ignored in Get Details Mode. ## `tracks_fetchDetails` (type: `boolean`): πŸ“Œ Search Mode only β€” in Get Details Mode the detail scraper always runs, this toggle is ignored. When ON β€” runs getTrack for every URI found in search results, merging full track metadata into each result. ⚠️ Slower β€” one extra API call per search result. ## `albums_search_offset` (type: `integer`): Starting position for search pagination. 0 = first page. πŸ“Œ Search Mode only β€” ignored in Get Details Mode. ## `albums_search_limit` (type: `integer`): Maximum number of album results to return. πŸ“Œ Search Mode only β€” ignored in Get Details Mode. ## `albums_search_numberOfTopResults` (type: `integer`): Number of top-ranked items highlighted in the response. πŸ“Œ Search Mode only β€” ignored in Get Details Mode. ## `albums_get_offset` (type: `integer`): Starting position in the album's track list. 0 = first track. πŸ“Œ Active in Get Details Mode (always) and in Search Mode only when 'Fetch Full Album Details' is ON. β›” Ignored in Search Mode when Fetch Details is OFF. ## `albums_get_limit` (type: `integer`): Maximum number of tracks to return from the album. πŸ“Œ Active in Get Details Mode (always) and in Search Mode only when 'Fetch Full Album Details' is ON. β›” Ignored in Search Mode when Fetch Details is OFF. ## `albums_fetchDetails` (type: `boolean`): πŸ“Œ Search Mode only β€” in Get Details Mode the detail scraper always runs, this toggle is ignored. When ON β€” runs getAlbum for every URI found in search results. This activates the Get: Track List Offset and Limit filters above. ⚠️ Slower β€” one extra API call per search result. ## `artists_search_offset` (type: `integer`): Starting position for search pagination. 0 = first page. πŸ“Œ Search Mode only β€” ignored in Get Details Mode. ## `artists_search_limit` (type: `integer`): Maximum number of artist results to return. πŸ“Œ Search Mode only β€” ignored in Get Details Mode. ## `artists_search_numberOfTopResults` (type: `integer`): Number of top-ranked items highlighted in the response. πŸ“Œ Search Mode only β€” ignored in Get Details Mode. ## `artists_fetchDetails` (type: `boolean`): πŸ“Œ Search Mode only β€” in Get Details Mode the detail scraper always runs, this toggle is ignored. When ON β€” runs queryArtistOverview for every URI found in search results, merging full artist metadata into each result. ⚠️ Slower β€” one extra API call per search result. ## `playlists_search_offset` (type: `integer`): Starting position for search pagination. 0 = first page. πŸ“Œ Search Mode only β€” ignored in Get Details Mode. ## `playlists_search_limit` (type: `integer`): Maximum number of playlist results to return. πŸ“Œ Search Mode only β€” ignored in Get Details Mode. ## `playlists_search_numberOfTopResults` (type: `integer`): Number of top-ranked items highlighted in the response. πŸ“Œ Search Mode only β€” ignored in Get Details Mode. ## `playlists_get_offset` (type: `integer`): Starting position in the playlist's track list. 0 = first track. πŸ“Œ Active in Get Details Mode (always) and in Search Mode only when 'Fetch Full Playlist Details' is ON. β›” Ignored in Search Mode when Fetch Details is OFF. ## `playlists_get_limit` (type: `integer`): Maximum number of tracks to return from the playlist. πŸ“Œ Active in Get Details Mode (always) and in Search Mode only when 'Fetch Full Playlist Details' is ON. β›” Ignored in Search Mode when Fetch Details is OFF. ## `playlists_fetchDetails` (type: `boolean`): πŸ“Œ Search Mode only β€” in Get Details Mode the detail scraper always runs, this toggle is ignored. When ON β€” runs fetchPlaylist for every URI found in search results. This activates the Get: Track List Offset and Limit filters above. ⚠️ Slower β€” one extra API call per search result. ## `genres_search_offset` (type: `integer`): Starting position for search pagination. 0 = first page. πŸ“Œ Search Mode only β€” ignored in Get Details Mode. ## `genres_search_limit` (type: `integer`): Maximum number of genre results to return. πŸ“Œ Search Mode only β€” ignored in Get Details Mode. ## `genres_search_numberOfTopResults` (type: `integer`): Number of top-ranked items highlighted in the response. πŸ“Œ Search Mode only β€” ignored in Get Details Mode. ## `genres_get_sectionLimit` (type: `integer`): Number of sections to fetch from the genre page (e.g. 'Popular Playlists', 'New Releases'). πŸ“Œ Active in Get Details Mode (always) and in Search Mode only when 'Fetch Full Genre Details' is ON. β›” Ignored in Search Mode when Fetch Details is OFF. ## `genres_get_sectionItemLimit` (type: `integer`): Maximum items returned inside each section when using browseSection. πŸ“Œ Only active when 'Include Section Details' is ON β€” otherwise browsePage returns a quick 10-item preview and this value is ignored. β›” Ignored in Search Mode when Fetch Details is OFF. ## `genres_includeSectionDetails` (type: `boolean`): Controls whether a separate browseSection API call runs for each section. β€’ ON β†’ runs browseSection per section, fetching full items up to Items Per Section limit. Activates the Items Per Section filter. β€’ OFF β†’ uses the quick 10-item preview from browsePage only (faster, fewer API calls). Items Per Section is ignored. βœ… Your ON/OFF choice is respected in both modes. πŸ“Œ In Get Details Mode β€” always available. In Search Mode β€” only when Fetch Full Genre Details is ON. β›” Ignored in Search Mode when Fetch Details is OFF. ## `genres_fetchDetails` (type: `boolean`): πŸ“Œ Search Mode only β€” in Get Details Mode the detail scraper always runs, this toggle is ignored. When ON β€” runs browsePage for every URI found in search results. This activates all Get: filters and toggle buttons above (How Many Sections, Items Per Section, Include Section Details). ⚠️ Slower β€” one or more extra API calls per search result. ## `users_search_offset` (type: `integer`): Starting position for search pagination. 0 = first page. πŸ“Œ Search Mode only. ## `users_search_limit` (type: `integer`): Maximum number of user results to return. πŸ“Œ Search Mode only. ## `users_search_numberOfTopResults` (type: `integer`): Number of top-ranked items highlighted in the response. πŸ“Œ Search Mode only. ## `audiobooks_search_offset` (type: `integer`): Starting position for search pagination. 0 = first page. πŸ“Œ Search Mode only β€” ignored in Get Details Mode. ## `audiobooks_search_limit` (type: `integer`): Maximum number of audiobook results to return. πŸ“Œ Search Mode only β€” ignored in Get Details Mode. ## `audiobooks_search_numberOfTopResults` (type: `integer`): Number of top-ranked items highlighted in the response. πŸ“Œ Search Mode only β€” ignored in Get Details Mode. ## `audiobooks_get_offset` (type: `integer`): Starting position in the chapter list. 0 = start from chapter 1. πŸ“Œ Active in Get Details Mode (always) and in Search Mode only when 'Fetch Full Audiobook Details' is ON. β›” Ignored in Search Mode when Fetch Details is OFF. ## `audiobooks_get_limit` (type: `integer`): Maximum number of chapters to fetch per audiobook. πŸ“Œ Active in Get Details Mode (always) and in Search Mode only when 'Fetch Full Audiobook Details' is ON. β›” Ignored in Search Mode when Fetch Details is OFF. ## `audiobooks_includeSimilar` (type: `boolean`): Controls whether the similarAudiobooks API call (3rd operation) runs to fetch recommendations. β€’ ON β†’ fetches similar audiobook recommendations β€’ OFF β†’ skips the 3rd operation (faster) βœ… Your ON/OFF choice is respected in both modes. πŸ“Œ In Get Details Mode β€” always available. In Search Mode β€” only when Fetch Full Audiobook Details is ON. β›” Ignored in Search Mode when Fetch Details is OFF. ⚠️ Spotify has retired this API in some regions β€” may return no data. ## `audiobooks_fetchDetails` (type: `boolean`): πŸ“Œ Search Mode only β€” in Get Details Mode the detail scraper always runs, this toggle is ignored. When ON β€” runs all 3 operations (metadata + chapters + optional similar) for every audiobook URI found in search results. This activates all Get: filters and toggle buttons above. ⚠️ Slower β€” multiple extra API calls per search result. ## `episodes_search_offset` (type: `integer`): Starting position for search pagination. 0 = first page. πŸ“Œ Search Mode only β€” ignored in Get Details Mode. ## `episodes_search_limit` (type: `integer`): Maximum number of episode results to return. πŸ“Œ Search Mode only β€” ignored in Get Details Mode. ## `episodes_includeRecommended` (type: `boolean`): Controls whether the internalLinkRecommenderEpisode API call (2nd operation) runs to fetch related episodes. β€’ ON β†’ fetches recommended episode suggestions β€’ OFF β†’ skips the 2nd operation (faster) βœ… Your ON/OFF choice is respected in both modes. πŸ“Œ In Get Details Mode β€” always available. In Search Mode β€” only when Fetch Full Episode Details is ON. β›” Ignored in Search Mode when Fetch Details is OFF. ⚠️ Spotify has retired this API in most regions β€” automatically skipped if the hash is not found. ## `episodes_fetchDetails` (type: `boolean`): πŸ“Œ Search Mode only β€” in Get Details Mode the detail scraper always runs, this toggle is ignored. When ON β€” runs getEpisodeOrChapter for every URI found in search results. This activates the Include Recommended Episodes toggle above. ⚠️ Slower β€” one or more extra API calls per search result. ## `podcasts_search_offset` (type: `integer`): Starting position for search pagination. 0 = first page. πŸ“Œ Search Mode only β€” ignored in Get Details Mode. ## `podcasts_search_limit` (type: `integer`): Maximum number of podcast results to return. πŸ“Œ Search Mode only β€” ignored in Get Details Mode. ## `podcasts_get_offset` (type: `integer`): Starting position in the episode list. 0 = most recent episode first. πŸ“Œ Active in Get Details Mode (always) and in Search Mode only when 'Fetch Full Podcast Details' is ON. β›” Ignored in Search Mode when Fetch Details is OFF. ## `podcasts_get_limit` (type: `integer`): Maximum number of episodes to fetch per podcast. Each podcast result gets this many episodes independently (e.g. limit=4 means 4 episodes per show). πŸ“Œ Active in Get Details Mode (always) and in Search Mode only when 'Fetch Full Podcast Details' is ON. β›” Ignored in Search Mode when Fetch Details is OFF. ## `podcasts_includeRecommended` (type: `boolean`): Controls whether the internalLinkRecommenderShow API call (3rd operation) runs to fetch related show recommendations. β€’ ON β†’ fetches recommended similar shows β€’ OFF β†’ skips the 3rd operation (faster) βœ… Your ON/OFF choice is respected in both modes. πŸ“Œ In Get Details Mode β€” always available. In Search Mode β€” only when Fetch Full Podcast Details is ON. β›” Ignored in Search Mode when Fetch Details is OFF. ⚠️ Spotify has retired this API in most regions β€” automatically skipped if the hash is not found. ## `podcasts_fetchDetails` (type: `boolean`): πŸ“Œ Search Mode only β€” in Get Details Mode the detail scraper always runs, this toggle is ignored. When ON β€” runs all 3 operations (metadata + episodes + optional recommended) for every podcast URI found in search results. This activates all Get: filters and toggle buttons above. ⚠️ Slower β€” multiple extra API calls per search result. ## Actor input object example ```json { "mode": "search", "searchType": "searchTracks", "keyword": [ "Rock", "Sun" ], "getDetailsType": "track", "spotifyUris": [ "spotify:track:0VjIjW4GlUZAMYd2vXMi3b", "https://open.spotify.com/track/7KA4W4McWYRpgf0fWsJZWB" ], "showDetailType": "podcast", "proxyCountry": "US", "tracks_search_offset": 0, "tracks_search_limit": 10, "tracks_search_numberOfTopResults": 10, "tracks_fetchDetails": false, "albums_search_offset": 0, "albums_search_limit": 30, "albums_search_numberOfTopResults": 20, "albums_get_offset": 0, "albums_get_limit": 50, "albums_fetchDetails": false, "artists_search_offset": 0, "artists_search_limit": 30, "artists_search_numberOfTopResults": 20, "artists_fetchDetails": false, "playlists_search_offset": 0, "playlists_search_limit": 30, "playlists_search_numberOfTopResults": 20, "playlists_get_offset": 0, "playlists_get_limit": 25, "playlists_fetchDetails": false, "genres_search_offset": 0, "genres_search_limit": 30, "genres_search_numberOfTopResults": 20, "genres_get_sectionLimit": 10, "genres_get_sectionItemLimit": 20, "genres_includeSectionDetails": false, "genres_fetchDetails": false, "users_search_offset": 0, "users_search_limit": 30, "users_search_numberOfTopResults": 20, "audiobooks_search_offset": 0, "audiobooks_search_limit": 30, "audiobooks_search_numberOfTopResults": 20, "audiobooks_get_offset": 0, "audiobooks_get_limit": 50, "audiobooks_includeSimilar": false, "audiobooks_fetchDetails": false, "episodes_search_offset": 0, "episodes_search_limit": 30, "episodes_includeRecommended": false, "episodes_fetchDetails": false, "podcasts_search_offset": 0, "podcasts_search_limit": 30, "podcasts_get_offset": 0, "podcasts_get_limit": 50, "podcasts_includeRecommended": false, "podcasts_fetchDetails": false } ``` # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "keyword": [ "Rock", "Sun" ], "spotifyUris": [ "spotify:track:0VjIjW4GlUZAMYd2vXMi3b", "https://open.spotify.com/track/7KA4W4McWYRpgf0fWsJZWB" ] }; // Run the Actor and wait for it to finish const run = await client.actor("apiharvest/spotify-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`πŸ’Ύ Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // πŸ“š Want to learn more πŸ“–? Go to β†’ https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "keyword": [ "Rock", "Sun", ], "spotifyUris": [ "spotify:track:0VjIjW4GlUZAMYd2vXMi3b", "https://open.spotify.com/track/7KA4W4McWYRpgf0fWsJZWB", ], } # Run the Actor and wait for it to finish run = client.actor("apiharvest/spotify-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("πŸ’Ύ Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # πŸ“š Want to learn more πŸ“–? Go to β†’ https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "keyword": [ "Rock", "Sun" ], "spotifyUris": [ "spotify:track:0VjIjW4GlUZAMYd2vXMi3b", "https://open.spotify.com/track/7KA4W4McWYRpgf0fWsJZWB" ] }' | apify call apiharvest/spotify-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=apiharvest/spotify-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Spotify Scraper ✨", "description": "Search tracks, albums, artists, playlists, genres, audiobooks, podcasts & episodes β€” multiple keywords per run. Fetch full metadata by URI/URL: track lists, chapters, episode counts, follower stats, popularity scores, release dates & cover images. No Spotify account required πŸ” Spotify Scraper✨", "version": "0.0", "x-build-id": "gexiKqWYvyQFmIVcb" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/apiharvest~spotify-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-apiharvest-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/apiharvest~spotify-scraper/runs": { "post": { "operationId": "runs-sync-apiharvest-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/apiharvest~spotify-scraper/run-sync": { "post": { "operationId": "run-sync-apiharvest-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", "required": [ "mode" ], "properties": { "mode": { "title": "🎯 Scraper Mode", "enum": [ "search", "get_details" ], "type": "string", "description": "Choose how to scrape Spotify:\n\nπŸ” Search Mode β€” enter a keyword and pick a Search Type. Returns ranked results.\n Active fields: Search Type, Search Keyword, and each type's filter section below.\n\nπŸ”— Get Details Mode β€” paste Spotify URIs/URLs and pick a Get Details Type. Returns full metadata.\n Active fields: Get Details Type, Spotify URIs / URLs, and each type's filter section below.", "default": "search" }, "searchType": { "title": "πŸ”Ž Search Type", "enum": [ "searchTracks", "searchAlbums", "searchArtists", "searchPlaylists", "searchGenres", "searchUsers", "searchAudiobooks", "searchFullEpisodes", "searchPodcasts" ], "type": "string", "description": "⚠️ Search Mode only β€” ignored in Get Details Mode.\n\nWhich Spotify category to search by keyword.\n🎡 Tracks Β· πŸ’Ώ Albums Β· 🎀 Artists Β· 🎧 Playlists Β· 🎨 Genres/Moods Β· πŸ‘€ Users Β· πŸ“š Audiobooks Β· πŸŽ™οΈ Full Episodes Β· πŸŽ™ Podcasts/Shows\n\nπŸ’‘ Each type also has a 'Fetch Full Details' toggle inside its own section below β€” turn it on to automatically run the matching get-detail scraper on every result URI found.", "default": "searchTracks" }, "keyword": { "title": "πŸ” Search Keyword(s)", "type": "array", "description": "⚠️ Search Mode only β€” ignored in Get Details Mode.\n\nOne or more search terms sent to Spotify. Each keyword runs as a separate search.\nUse full track names, artist names, or titles for accurate results.\n\nπŸ’‘ Add multiple keywords β€” one per entry β€” to search for several terms in a single run.", "items": { "type": "string" } }, "getDetailsType": { "title": "πŸ”— Get Details Type", "enum": [ "track", "album", "artist", "playlist", "genre", "audiobook", "podcast", "episode" ], "type": "string", "description": "⚠️ Get Details Mode only β€” ignored in Search Mode.\n\nSelect which Spotify entity type you are fetching. This must match the URIs you paste below.\n🎡 Track Β· πŸ’Ώ Album Β· 🎀 Artist Β· 🎧 Playlist Β· 🎨 Genre/Mood Β· πŸ“š Audiobook Β· πŸŽ™ Podcast/Show Β· πŸŽ™οΈ Full Episode\n\nπŸ’‘ For spotify:show: URIs β€” select Audiobook or Podcast/Show explicitly since both share the same URI prefix.", "default": "track" }, "spotifyUris": { "title": "πŸ”— Spotify URIs / URLs", "type": "array", "description": "⚠️ Get Details Mode only β€” ignored in Search Mode.\n\nOne or more Spotify URIs or open.spotify.com URLs to fetch.\nExamples: spotify:track:ID Β· https://open.spotify.com/album/ID\n\nπŸ’‘ All URIs must be the same entity type β€” select the matching type in Get Details Type above.", "items": { "type": "string" } }, "showDetailType": { "title": "❓ Show URI Type β€” Audiobook or Podcast?", "enum": [ "podcast", "audiobook" ], "type": "string", "description": "⚠️ This field is no longer needed. Use Get Details Type above to select Audiobook or Podcast/Show explicitly.\n\nKept for backward compatibility only. Ignored when Get Details Type is set.", "default": "podcast" }, "proxyCountry": { "title": "🌐 Proxy Country", "enum": [ "US", "GB", "AU", "CA", "DE", "FR", "NL", "IT", "ES", "SE", "NO", "DK", "FI", "BE", "AT", "CH", "IE", "PL", "PT", "CZ", "HU", "RO", "GR", "BG", "HR", "SK", "RS", "JP", "KR", "SG", "HK", "TW", "TH", "MY", "ID", "PH", "VN", "IN", "BR", "MX", "AR", "CL", "CO", "PE", "ZA", "NG", "KE", "EG", "SA", "AE", "TR", "IL", "UA", "RU", "BY" ], "type": "string", "description": "Residential proxy exit country β€” Spotify sees your requests as coming from this location.\n\n⭐ US recommended β€” widest catalog, only country guaranteed for ALL scraper types (Tracks, Albums, Artists, Playlists, Audiobooks, Podcasts, Episodes).\n\n⚠️ Regional restrictions:\nβ€’ Podcasts & Episodes β†’ require US, GB, AU, or CA\nβ€’ Audiobooks β†’ US, GB, AU, CA only\nβ€’ Music (Tracks/Albums/Artists) β†’ works in most countries\n\nIf results are empty, switch to US. If US still returns empty, it's a script or API issue β€” contact the developer.", "default": "US" }, "tracks_search_offset": { "title": "🎡 Tracks β€” πŸ“„ Search Offset", "minimum": 0, "type": "integer", "description": "Starting position for search pagination. 0 = first page.\nπŸ“Œ Search Mode only β€” ignored in Get Details Mode.", "default": 0 }, "tracks_search_limit": { "title": "🎡 Tracks β€” πŸ“Š Search Limit", "minimum": 1, "type": "integer", "description": "Maximum number of track results to return.\nπŸ“Œ Search Mode only β€” ignored in Get Details Mode.", "default": 10 }, "tracks_search_numberOfTopResults": { "title": "🎡 Tracks β€” πŸ† Top Results Count", "minimum": 1, "type": "integer", "description": "Number of top-ranked items highlighted in the response.\nπŸ“Œ Search Mode only β€” ignored in Get Details Mode.", "default": 10 }, "tracks_fetchDetails": { "title": "🎡 Tracks β€” πŸ”„ Fetch Full Track Details", "type": "boolean", "description": "πŸ“Œ Search Mode only β€” in Get Details Mode the detail scraper always runs, this toggle is ignored.\nWhen ON β€” runs getTrack for every URI found in search results, merging full track metadata into each result.\n⚠️ Slower β€” one extra API call per search result.", "default": false }, "albums_search_offset": { "title": "πŸ’Ώ Albums β€” πŸ“„ Search Offset", "minimum": 0, "type": "integer", "description": "Starting position for search pagination. 0 = first page.\nπŸ“Œ Search Mode only β€” ignored in Get Details Mode.", "default": 0 }, "albums_search_limit": { "title": "πŸ’Ώ Albums β€” πŸ“Š Search Limit", "minimum": 1, "type": "integer", "description": "Maximum number of album results to return.\nπŸ“Œ Search Mode only β€” ignored in Get Details Mode.", "default": 30 }, "albums_search_numberOfTopResults": { "title": "πŸ’Ώ Albums β€” πŸ† Top Results Count", "minimum": 1, "type": "integer", "description": "Number of top-ranked items highlighted in the response.\nπŸ“Œ Search Mode only β€” ignored in Get Details Mode.", "default": 20 }, "albums_get_offset": { "title": "πŸ’Ώ Albums β€” πŸ“„ Get: Track List Offset", "minimum": 0, "type": "integer", "description": "Starting position in the album's track list. 0 = first track.\nπŸ“Œ Active in Get Details Mode (always) and in Search Mode only when 'Fetch Full Album Details' is ON.\nβ›” Ignored in Search Mode when Fetch Details is OFF.", "default": 0 }, "albums_get_limit": { "title": "πŸ’Ώ Albums β€” πŸ“Š Get: Track List Limit", "minimum": 1, "type": "integer", "description": "Maximum number of tracks to return from the album.\nπŸ“Œ Active in Get Details Mode (always) and in Search Mode only when 'Fetch Full Album Details' is ON.\nβ›” Ignored in Search Mode when Fetch Details is OFF.", "default": 50 }, "albums_fetchDetails": { "title": "πŸ’Ώ Albums β€” πŸ”„ Fetch Full Album Details", "type": "boolean", "description": "πŸ“Œ Search Mode only β€” in Get Details Mode the detail scraper always runs, this toggle is ignored.\nWhen ON β€” runs getAlbum for every URI found in search results. This activates the Get: Track List Offset and Limit filters above.\n⚠️ Slower β€” one extra API call per search result.", "default": false }, "artists_search_offset": { "title": "🎀 Artists β€” πŸ“„ Search Offset", "minimum": 0, "type": "integer", "description": "Starting position for search pagination. 0 = first page.\nπŸ“Œ Search Mode only β€” ignored in Get Details Mode.", "default": 0 }, "artists_search_limit": { "title": "🎀 Artists β€” πŸ“Š Search Limit", "minimum": 1, "type": "integer", "description": "Maximum number of artist results to return.\nπŸ“Œ Search Mode only β€” ignored in Get Details Mode.", "default": 30 }, "artists_search_numberOfTopResults": { "title": "🎀 Artists β€” πŸ† Top Results Count", "minimum": 1, "type": "integer", "description": "Number of top-ranked items highlighted in the response.\nπŸ“Œ Search Mode only β€” ignored in Get Details Mode.", "default": 20 }, "artists_fetchDetails": { "title": "🎀 Artists β€” πŸ”„ Fetch Full Artist Details", "type": "boolean", "description": "πŸ“Œ Search Mode only β€” in Get Details Mode the detail scraper always runs, this toggle is ignored.\nWhen ON β€” runs queryArtistOverview for every URI found in search results, merging full artist metadata into each result.\n⚠️ Slower β€” one extra API call per search result.", "default": false }, "playlists_search_offset": { "title": "🎧 Playlists β€” πŸ“„ Search Offset", "minimum": 0, "type": "integer", "description": "Starting position for search pagination. 0 = first page.\nπŸ“Œ Search Mode only β€” ignored in Get Details Mode.", "default": 0 }, "playlists_search_limit": { "title": "🎧 Playlists β€” πŸ“Š Search Limit", "minimum": 1, "type": "integer", "description": "Maximum number of playlist results to return.\nπŸ“Œ Search Mode only β€” ignored in Get Details Mode.", "default": 30 }, "playlists_search_numberOfTopResults": { "title": "🎧 Playlists β€” πŸ† Top Results Count", "minimum": 1, "type": "integer", "description": "Number of top-ranked items highlighted in the response.\nπŸ“Œ Search Mode only β€” ignored in Get Details Mode.", "default": 20 }, "playlists_get_offset": { "title": "🎧 Playlists β€” πŸ“„ Get: Track List Offset", "minimum": 0, "type": "integer", "description": "Starting position in the playlist's track list. 0 = first track.\nπŸ“Œ Active in Get Details Mode (always) and in Search Mode only when 'Fetch Full Playlist Details' is ON.\nβ›” Ignored in Search Mode when Fetch Details is OFF.", "default": 0 }, "playlists_get_limit": { "title": "🎧 Playlists β€” πŸ“Š Get: Track List Limit", "minimum": 1, "type": "integer", "description": "Maximum number of tracks to return from the playlist.\nπŸ“Œ Active in Get Details Mode (always) and in Search Mode only when 'Fetch Full Playlist Details' is ON.\nβ›” Ignored in Search Mode when Fetch Details is OFF.", "default": 25 }, "playlists_fetchDetails": { "title": "🎧 Playlists β€” πŸ”„ Fetch Full Playlist Details", "type": "boolean", "description": "πŸ“Œ Search Mode only β€” in Get Details Mode the detail scraper always runs, this toggle is ignored.\nWhen ON β€” runs fetchPlaylist for every URI found in search results. This activates the Get: Track List Offset and Limit filters above.\n⚠️ Slower β€” one extra API call per search result.", "default": false }, "genres_search_offset": { "title": "🎨 Genres β€” πŸ“„ Search Offset", "minimum": 0, "type": "integer", "description": "Starting position for search pagination. 0 = first page.\nπŸ“Œ Search Mode only β€” ignored in Get Details Mode.", "default": 0 }, "genres_search_limit": { "title": "🎨 Genres β€” πŸ“Š Search Limit", "minimum": 1, "type": "integer", "description": "Maximum number of genre results to return.\nπŸ“Œ Search Mode only β€” ignored in Get Details Mode.", "default": 30 }, "genres_search_numberOfTopResults": { "title": "🎨 Genres β€” πŸ† Top Results Count", "minimum": 1, "type": "integer", "description": "Number of top-ranked items highlighted in the response.\nπŸ“Œ Search Mode only β€” ignored in Get Details Mode.", "default": 20 }, "genres_get_sectionLimit": { "title": "🎨 Genres β€” πŸ“Š Get: How Many Sections", "minimum": 1, "type": "integer", "description": "Number of sections to fetch from the genre page (e.g. 'Popular Playlists', 'New Releases').\nπŸ“Œ Active in Get Details Mode (always) and in Search Mode only when 'Fetch Full Genre Details' is ON.\nβ›” Ignored in Search Mode when Fetch Details is OFF.", "default": 10 }, "genres_get_sectionItemLimit": { "title": "🎨 Genres β€” πŸ“Š Get: Items Per Section", "minimum": 1, "type": "integer", "description": "Maximum items returned inside each section when using browseSection.\nπŸ“Œ Only active when 'Include Section Details' is ON β€” otherwise browsePage returns a quick 10-item preview and this value is ignored.\nβ›” Ignored in Search Mode when Fetch Details is OFF.", "default": 20 }, "genres_includeSectionDetails": { "title": "🎨 Genres β€” πŸ” Include Section Details", "type": "boolean", "description": "Controls whether a separate browseSection API call runs for each section.\nβ€’ ON β†’ runs browseSection per section, fetching full items up to Items Per Section limit. Activates the Items Per Section filter.\nβ€’ OFF β†’ uses the quick 10-item preview from browsePage only (faster, fewer API calls). Items Per Section is ignored.\nβœ… Your ON/OFF choice is respected in both modes.\nπŸ“Œ In Get Details Mode β€” always available. In Search Mode β€” only when Fetch Full Genre Details is ON.\nβ›” Ignored in Search Mode when Fetch Details is OFF.", "default": false }, "genres_fetchDetails": { "title": "🎨 Genres β€” πŸ”„ Fetch Full Genre Details", "type": "boolean", "description": "πŸ“Œ Search Mode only β€” in Get Details Mode the detail scraper always runs, this toggle is ignored.\nWhen ON β€” runs browsePage for every URI found in search results. This activates all Get: filters and toggle buttons above (How Many Sections, Items Per Section, Include Section Details).\n⚠️ Slower β€” one or more extra API calls per search result.", "default": false }, "users_search_offset": { "title": "πŸ‘€ Users β€” πŸ“„ Search Offset", "minimum": 0, "type": "integer", "description": "Starting position for search pagination. 0 = first page.\nπŸ“Œ Search Mode only.", "default": 0 }, "users_search_limit": { "title": "πŸ‘€ Users β€” πŸ“Š Search Limit", "minimum": 1, "type": "integer", "description": "Maximum number of user results to return.\nπŸ“Œ Search Mode only.", "default": 30 }, "users_search_numberOfTopResults": { "title": "πŸ‘€ Users β€” πŸ† Top Results Count", "minimum": 1, "type": "integer", "description": "Number of top-ranked items highlighted in the response.\nπŸ“Œ Search Mode only.", "default": 20 }, "audiobooks_search_offset": { "title": "πŸ“š Audiobooks β€” πŸ“„ Search Offset", "minimum": 0, "type": "integer", "description": "Starting position for search pagination. 0 = first page.\nπŸ“Œ Search Mode only β€” ignored in Get Details Mode.", "default": 0 }, "audiobooks_search_limit": { "title": "πŸ“š Audiobooks β€” πŸ“Š Search Limit", "minimum": 1, "type": "integer", "description": "Maximum number of audiobook results to return.\nπŸ“Œ Search Mode only β€” ignored in Get Details Mode.", "default": 30 }, "audiobooks_search_numberOfTopResults": { "title": "πŸ“š Audiobooks β€” πŸ† Top Results Count", "minimum": 1, "type": "integer", "description": "Number of top-ranked items highlighted in the response.\nπŸ“Œ Search Mode only β€” ignored in Get Details Mode.", "default": 20 }, "audiobooks_get_offset": { "title": "πŸ“š Audiobooks β€” πŸ“„ Get: Chapter List Offset", "minimum": 0, "type": "integer", "description": "Starting position in the chapter list. 0 = start from chapter 1.\nπŸ“Œ Active in Get Details Mode (always) and in Search Mode only when 'Fetch Full Audiobook Details' is ON.\nβ›” Ignored in Search Mode when Fetch Details is OFF.", "default": 0 }, "audiobooks_get_limit": { "title": "πŸ“š Audiobooks β€” πŸ“Š Get: Chapter List Limit", "minimum": 1, "type": "integer", "description": "Maximum number of chapters to fetch per audiobook.\nπŸ“Œ Active in Get Details Mode (always) and in Search Mode only when 'Fetch Full Audiobook Details' is ON.\nβ›” Ignored in Search Mode when Fetch Details is OFF.", "default": 50 }, "audiobooks_includeSimilar": { "title": "πŸ“š Audiobooks β€” πŸ”— Include Similar Audiobooks", "type": "boolean", "description": "Controls whether the similarAudiobooks API call (3rd operation) runs to fetch recommendations.\nβ€’ ON β†’ fetches similar audiobook recommendations\nβ€’ OFF β†’ skips the 3rd operation (faster)\nβœ… Your ON/OFF choice is respected in both modes.\nπŸ“Œ In Get Details Mode β€” always available. In Search Mode β€” only when Fetch Full Audiobook Details is ON.\nβ›” Ignored in Search Mode when Fetch Details is OFF.\n⚠️ Spotify has retired this API in some regions β€” may return no data.", "default": false }, "audiobooks_fetchDetails": { "title": "πŸ“š Audiobooks β€” πŸ”„ Fetch Full Audiobook Details", "type": "boolean", "description": "πŸ“Œ Search Mode only β€” in Get Details Mode the detail scraper always runs, this toggle is ignored.\nWhen ON β€” runs all 3 operations (metadata + chapters + optional similar) for every audiobook URI found in search results. This activates all Get: filters and toggle buttons above.\n⚠️ Slower β€” multiple extra API calls per search result.", "default": false }, "episodes_search_offset": { "title": "πŸŽ™οΈ Episodes β€” πŸ“„ Search Offset", "minimum": 0, "type": "integer", "description": "Starting position for search pagination. 0 = first page.\nπŸ“Œ Search Mode only β€” ignored in Get Details Mode.", "default": 0 }, "episodes_search_limit": { "title": "πŸŽ™οΈ Episodes β€” πŸ“Š Search Limit", "minimum": 1, "type": "integer", "description": "Maximum number of episode results to return.\nπŸ“Œ Search Mode only β€” ignored in Get Details Mode.", "default": 30 }, "episodes_includeRecommended": { "title": "πŸŽ™οΈ Episodes β€” πŸ’‘ Include Recommended Episodes", "type": "boolean", "description": "Controls whether the internalLinkRecommenderEpisode API call (2nd operation) runs to fetch related episodes.\nβ€’ ON β†’ fetches recommended episode suggestions\nβ€’ OFF β†’ skips the 2nd operation (faster)\nβœ… Your ON/OFF choice is respected in both modes.\nπŸ“Œ In Get Details Mode β€” always available. In Search Mode β€” only when Fetch Full Episode Details is ON.\nβ›” Ignored in Search Mode when Fetch Details is OFF.\n⚠️ Spotify has retired this API in most regions β€” automatically skipped if the hash is not found.", "default": false }, "episodes_fetchDetails": { "title": "πŸŽ™οΈ Episodes β€” πŸ”„ Fetch Full Episode Details", "type": "boolean", "description": "πŸ“Œ Search Mode only β€” in Get Details Mode the detail scraper always runs, this toggle is ignored.\nWhen ON β€” runs getEpisodeOrChapter for every URI found in search results. This activates the Include Recommended Episodes toggle above.\n⚠️ Slower β€” one or more extra API calls per search result.", "default": false }, "podcasts_search_offset": { "title": "πŸŽ™ Podcasts β€” πŸ“„ Search Offset", "minimum": 0, "type": "integer", "description": "Starting position for search pagination. 0 = first page.\nπŸ“Œ Search Mode only β€” ignored in Get Details Mode.", "default": 0 }, "podcasts_search_limit": { "title": "πŸŽ™ Podcasts β€” πŸ“Š Search Limit", "minimum": 1, "type": "integer", "description": "Maximum number of podcast results to return.\nπŸ“Œ Search Mode only β€” ignored in Get Details Mode.", "default": 30 }, "podcasts_get_offset": { "title": "πŸŽ™ Podcasts β€” πŸ“„ Get: Episode List Offset", "minimum": 0, "type": "integer", "description": "Starting position in the episode list. 0 = most recent episode first.\nπŸ“Œ Active in Get Details Mode (always) and in Search Mode only when 'Fetch Full Podcast Details' is ON.\nβ›” Ignored in Search Mode when Fetch Details is OFF.", "default": 0 }, "podcasts_get_limit": { "title": "πŸŽ™ Podcasts β€” πŸ“Š Get: Episode List Limit", "minimum": 1, "type": "integer", "description": "Maximum number of episodes to fetch per podcast.\nEach podcast result gets this many episodes independently (e.g. limit=4 means 4 episodes per show).\nπŸ“Œ Active in Get Details Mode (always) and in Search Mode only when 'Fetch Full Podcast Details' is ON.\nβ›” Ignored in Search Mode when Fetch Details is OFF.", "default": 50 }, "podcasts_includeRecommended": { "title": "πŸŽ™ Podcasts β€” πŸ’‘ Include Recommended Shows", "type": "boolean", "description": "Controls whether the internalLinkRecommenderShow API call (3rd operation) runs to fetch related show recommendations.\nβ€’ ON β†’ fetches recommended similar shows\nβ€’ OFF β†’ skips the 3rd operation (faster)\nβœ… Your ON/OFF choice is respected in both modes.\nπŸ“Œ In Get Details Mode β€” always available. In Search Mode β€” only when Fetch Full Podcast Details is ON.\nβ›” Ignored in Search Mode when Fetch Details is OFF.\n⚠️ Spotify has retired this API in most regions β€” automatically skipped if the hash is not found.", "default": false }, "podcasts_fetchDetails": { "title": "πŸŽ™ Podcasts β€” πŸ”„ Fetch Full Podcast Details", "type": "boolean", "description": "πŸ“Œ Search Mode only β€” in Get Details Mode the detail scraper always runs, this toggle is ignored.\nWhen ON β€” runs all 3 operations (metadata + episodes + optional recommended) for every podcast URI found in search results. This activates all Get: filters and toggle buttons above.\n⚠️ Slower β€” multiple extra API calls per search result.", "default": false } } }, "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 } } } } } } } } } } ```