{
  "openapi": "3.0.1",
  "info": {
    "title": "Spotify Scraper—Play Counts, Monthly Listeners & Playlists",
    "description": "Spotify play counts for tracks, albums, playlists and whole discographies, plus monthly listeners, world rank, charts with streams, lyrics and podcasts. Paste any link. Pay per result.",
    "version": "1.0",
    "x-build-id": "qv50lf1tWdSQf1VKl"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/eduair94~spotify-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-eduair94-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/eduair94~spotify-scraper/runs": {
      "post": {
        "operationId": "runs-sync-eduair94-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/eduair94~spotify-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-eduair94-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": [
          "category"
        ],
        "properties": {
          "category": {
            "title": "Data category",
            "enum": [
              "auto",
              "track_play_count",
              "album_play_counts",
              "artist_play_counts",
              "artist_discography_play_counts",
              "playlist_play_counts",
              "isrc",
              "track",
              "track_credits",
              "track_lyrics",
              "audio_features",
              "album",
              "album_tracks",
              "album_metadata",
              "album_by_upc",
              "artist",
              "artist_overview",
              "artist_albums",
              "artist_singles",
              "artist_appears_on",
              "artist_discovered_on",
              "artist_featuring",
              "artist_related",
              "artist_discography_overview",
              "playlist",
              "playlist_tracks",
              "user_profile",
              "user_followers",
              "show",
              "show_episodes",
              "episode",
              "recommendations",
              "partner_playlist",
              "partner_track",
              "partner_album",
              "partner_artist_overview",
              "partner_artist_discography",
              "concerts_by_location",
              "search_concert_locations",
              "artist_concerts",
              "search_concert_artists",
              "partner_concert",
              "search_multi",
              "search_tracks",
              "search_artists",
              "search_albums",
              "search_playlists",
              "search_users",
              "search_podcasts",
              "search_episodes",
              "search_genres",
              "search_top_results",
              "search_suggestions",
              "search_lyrics",
              "chart_top_200_tracks",
              "chart_viral_tracks",
              "chart_top_artists",
              "chart_top_albums",
              "chart_top_monthly_listeners",
              "chart_top_followers",
              "new_releases"
            ],
            "type": "string",
            "description": "Which data to extract. Leave it on 'Auto' to paste any mix of Spotify links: each link is scraped according to its type (track → track with play count, album → album, artist → artist profile with monthly listeners, followers, world rank and top cities, playlist → playlist, user → profile, show → podcast, episode → episode). Plain text is searched on Spotify and resolved to its top match; other links (other sites, audiobooks, local files) and malformed IDs fail without a search or a charge.\n\n▶ Play counts (stream counts):\n• 'track_play_count' = all-time play count of each track.\n• 'album_play_counts' = play count of every track on an album, with the album's label, release date and total.\n• 'artist_play_counts' = an artist's top tracks with play counts, plus monthly listeners, followers and world rank.\n• 'artist_discography_play_counts' = every track of an artist's albums, singles, EPs and compilations (newest first, up to 'Max results per query' rows per artist).\n• 'playlist_play_counts' = every track of a playlist with its play count and position.\n• 'isrc' = input ISRC codes (e.g. USUG11904206): the matching track with its play count.\nSpotify reports 0 until a track passes 1,000 streams.\n\n▶ Charts and new releases: enter country codes (US, GB, GLOBAL…) as the input; anything else is ignored and the Market below is used. A new-releases list that Spotify has not refreshed for over 30 days is not delivered (nothing is charged).\n\n▶ Other inputs: 'album_by_upc' takes UPC/EAN barcodes; 'audio_features' takes track links or IDs (25 per request).\n\n⚠️ Concert categories — pick the right one:\n• 'search_concert_locations' = look up CITIES/PLACES (input: place names like 'London'). Returns geoHash/geonameId.\n• 'search_concert_artists' = upcoming concerts BY ARTIST NAME (input: artist names like 'The Fratellis').\n• 'artist_concerts' = the same with a Spotify artist ID/URL.\n• 'concerts_by_location' = every concert at a geoHash.",
            "default": "auto"
          },
          "queries": {
            "title": "Spotify links, IDs or keywords",
            "type": "array",
            "description": "One per line. Auto and the ID categories: open.spotify.com links (including /intl-xx/ and /embed/ links), spotify.link short links, spotify: URIs or bare 22-character IDs. Search categories: keywords. Charts and new releases: country codes such as US, GB or GLOBAL. 'isrc': ISRC codes; 'album_by_upc': UPC/EAN barcodes. The same entity entered twice is scraped and charged once.",
            "items": {
              "type": "string"
            }
          },
          "defaultType": {
            "title": "Type of bare IDs (Auto)",
            "enum": [
              "track",
              "album",
              "artist",
              "playlist",
              "show",
              "episode"
            ],
            "type": "string",
            "description": "Category Auto only: how to read a bare 22-character ID. Links and spotify: URIs always use their own type.",
            "default": "track"
          },
          "maxResultsPerQuery": {
            "title": "Max results per query",
            "minimum": 1,
            "maximum": 1000,
            "type": "integer",
            "description": "Rows per input for list categories (playlist and album tracklists, discographies, search results, charts, new releases, podcast episodes, album, playlist and discography play counts). Long lists are paged automatically up to 1,000 rows. Spotify returns at most 50 for 'appears on' and 'discovered on'. Single-entity categories always return one row.",
            "default": 50
          },
          "concurrency": {
            "title": "Parallel inputs",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "Inputs processed at once. Tracks and artists are fetched 50 per request, albums 20 and audio features 25, so such a group counts as one input here. The Actor slows down automatically while Spotify is throttling and speeds up again afterwards.",
            "default": 5
          },
          "delayMs": {
            "title": "Delay between requests (ms)",
            "minimum": 0,
            "maximum": 60000,
            "type": "integer",
            "description": "Pause after each input (or each group of inputs fetched in one request). Use 0 for max speed.",
            "default": 0
          },
          "market": {
            "title": "Market (ISO 3166-1 alpha-2)",
            "type": "string",
            "description": "2-letter country code for regional results (e.g. US, GB, DE). Charts and new releases use it when the input names no country.",
            "default": "US"
          },
          "chartDate": {
            "title": "Chart date (YYYY-MM-DD)",
            "type": "string",
            "description": "For chart categories (leave empty for the latest chart) and the start date of 'concerts_by_location'."
          },
          "geoHash": {
            "title": "GeoHash (artist_concerts)",
            "type": "string",
            "description": "Optional location filter for 'artist_concerts' and 'search_concert_artists'. Spotify geohash (e.g. '6cb19y38v7py' for London). Leave empty for global tour data."
          },
          "enrichConcertDetails": {
            "title": "Deep concert search (enrich each concert with full details)",
            "type": "boolean",
            "description": "Enriches every concert with venue name, address (city / region / country / coordinates), lineup, ticket providers and related concerts, at 1 extra request per concert (capped by 'concertDetailsLimit'). Left unset, it is on for 'artist_concerts' and 'search_concert_artists' (which otherwise only return the city) and off elsewhere."
          },
          "concertDetailsLimit": {
            "title": "Max concerts to enrich per query",
            "minimum": 1,
            "maximum": 50,
            "type": "integer",
            "description": "Cap on how many concerts get enriched when 'enrichConcertDetails' is on. Avoids rate limits.",
            "default": 20
          },
          "parsedConcerts": {
            "title": "Parsed concert payloads (clean flat shape)",
            "type": "boolean",
            "description": "Return concert data in a normalized flat shape (artists, offers, location, related concerts) instead of raw GraphQL response. Affects 'partner_concert', 'artist_concerts', 'search_concert_artists', and enriched details.",
            "default": false
          },
          "includeRaw": {
            "title": "Include raw upstream payload",
            "type": "boolean",
            "description": "Keep the full upstream object under 'data' (instead of a copy without music videos, merch and other presentation blocks) and attach the whole response under 'raw' for single-entity categories. Off by default for slimmer output.",
            "default": false
          },
          "enrichWithContrast": {
            "title": "Cross-platform enrichment",
            "enum": [
              "",
              "ytmusic",
              "applemusic",
              "amazonmusic",
              "pandora",
              "gaana",
              "tencent"
            ],
            "type": "string",
            "description": "Attach the matching entity on another streaming platform to track, album, artist, artist overview and album metadata rows (under 'contrast'). Optional.",
            "default": ""
          },
          "mode": {
            "title": "Operation mode (deprecated)",
            "enum": [
              "get",
              "search",
              "chart"
            ],
            "type": "string",
            "description": "Ignored: the data category decides the mode. Kept so older saved inputs keep working."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}