{ "openapi": "3.0.1", "info": { "title": "Spotify Scraper - Artists, Playlists & Tracks", "description": "Scrape public Spotify artists, tracks, albums, playlists and podcasts. Get available listener and play counts, discover artists and track playlist or catalog changes. Export JSON or CSV and schedule repeat runs.", "version": "0.1", "x-build-id": "LchwMpLc0pT0r2wSf" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/fetchfinch~spotify-public-catalog-metadata/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-fetchfinch-spotify-public-catalog-metadata", "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/fetchfinch~spotify-public-catalog-metadata/runs": { "post": { "operationId": "runs-sync-fetchfinch-spotify-public-catalog-metadata", "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/fetchfinch~spotify-public-catalog-metadata/run-sync": { "post": { "operationId": "run-sync-fetchfinch-spotify-public-catalog-metadata", "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": { "mode": { "title": "Run mode", "enum": [ "snapshot", "monitor", "playlist_intelligence", "discover" ], "type": "string", "description": "Snapshot returns current records. Monitor tracks changes. Playlist intelligence adds graph and composition records. Discover runs an artist-focused enriched search.", "default": "snapshot" }, "stateStoreName": { "title": "Monitor state store", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$", "type": "string", "description": "Named Apify Key-Value Store used to keep the previous successful snapshot in monitor mode.", "default": "spotify-catalog-monitor" }, "historyDatasetName": { "title": "History dataset", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$", "type": "string", "description": "Named Apify Dataset used to append successful snapshots in monitor mode.", "default": "spotify-catalog-history" }, "onlyChanges": { "title": "Output changes only", "type": "boolean", "description": "In monitor mode, omit current snapshot records from the default dataset and return only change records.", "default": false }, "changePreset": { "title": "Change preset", "enum": [ "all_changes", "playlist_changes", "metrics_only" ], "type": "string", "description": "Choose which monitor events should be emitted after the first snapshot.", "default": "all_changes" }, "ignoredFields": { "title": "Ignored fields", "maxItems": 50, "type": "array", "description": "Optional exact JSON field paths to ignore during monitor comparisons.", "items": { "type": "string" } }, "metricThresholdPercent": { "title": "Metric threshold (%)", "minimum": 0, "maximum": 100, "type": "number", "description": "Ignore monitored numeric metric changes smaller than this percentage.", "default": 0 }, "maxGraphNodes": { "title": "Maximum graph nodes", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Upper bound for node records emitted by playlist intelligence mode.", "default": 1000 }, "rankBy": { "title": "Discovery ranking", "enum": [ "monthly_listeners", "followers", "release_count", "top_track_count" ], "type": "string", "description": "Artist field used to rank enriched discovery results.", "default": "monthly_listeners" }, "minMonthlyListeners": { "title": "Minimum monthly listeners", "minimum": 0, "type": "integer", "description": "In discover mode, keep only artists at or above this monthly listener count." }, "maxMonthlyListeners": { "title": "Maximum monthly listeners", "minimum": 0, "type": "integer", "description": "In discover mode, keep only artists at or below this monthly listener count." }, "minFollowers": { "title": "Minimum followers", "minimum": 0, "type": "integer", "description": "In discover mode, keep only artists at or above this follower count." }, "maxFollowers": { "title": "Maximum followers", "minimum": 0, "type": "integer", "description": "In discover mode, keep only artists at or below this follower count." }, "minReleases": { "title": "Minimum releases", "minimum": 0, "type": "integer", "description": "In discover mode, keep only artists with at least this many releases." }, "targets": { "title": "Spotify URLs, URIs, or IDs", "maxItems": 1000, "type": "array", "description": "Spotify URLs or spotify:type:id URIs. Raw 22-character IDs are also accepted when Target type is selected.", "items": { "type": "string" } }, "targetType": { "title": "Target type", "enum": [ "auto", "track", "album", "artist", "playlist", "show", "episode" ], "type": "string", "description": "Use Auto for URLs and URIs. Select an entity type when providing raw Spotify IDs.", "default": "auto" }, "searchQueries": { "title": "Search queries", "maxItems": 50, "type": "array", "description": "Optional public Spotify catalog searches. Search results are sparse unless Enrich search results is enabled.", "items": { "type": "string" } }, "searchTypes": { "title": "Search entity types", "type": "array", "description": "Entity sections to request for each search query.", "default": [ "track", "album", "artist", "playlist", "show", "episode" ], "items": { "type": "string" } }, "enrichSearchResults": { "title": "Enrich search results", "type": "boolean", "description": "Fetch each search hit again as a full entity. This is slower and creates more Spotify requests.", "default": false }, "maxSearchResults": { "title": "Results per search section", "minimum": 1, "maximum": 50, "type": "integer", "description": "Maximum results per entity type and query.", "default": 20 }, "maxItems": { "title": "Maximum output records", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Maximum current snapshot records, including error records. Monitor mode may additionally emit one change record per successful entity.", "default": 100 }, "maxTracks": { "title": "Maximum playlist tracks", "minimum": 1, "maximum": 500, "type": "integer", "description": "Maximum tracks loaded for each playlist. Album tracklists are fetched by the library as provided by Spotify.", "default": 100 }, "maxEpisodes": { "title": "Maximum show episodes", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Maximum episodes loaded for each podcast show.", "default": 50 }, "maxConcurrency": { "title": "Maximum concurrency", "minimum": 1, "maximum": 10, "type": "integer", "description": "Number of entity pipelines allowed to run concurrently. Lower values reduce request pressure.", "default": 5 }, "timeoutSecs": { "title": "Request timeout (seconds)", "minimum": 5, "maximum": 60, "type": "integer", "description": "Timeout applied to each catalog request.", "default": 15 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Optional Apify Proxy configuration for Spotify requests.", "default": { "useApifyProxy": 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 }, "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 } } } } } } } } } }