{
  "openapi": "3.0.1",
  "info": {
    "title": "Spotify Play Count & Insights Scraper",
    "description": "Exact stream counts, monthly listeners, world rank, full discography PLUS historical trend tracking, related artists, playlists, contact info (emails/socials), revenue estimates, lyrics and podcasts. Drop-in superset of beatanalytics/spotify-play-count-scraper.",
    "version": "1.0",
    "x-build-id": "bbwrXKhoTyjccX6al"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/brilliant_gum~spotify-insights-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-brilliant_gum-spotify-insights-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/brilliant_gum~spotify-insights-scraper/runs": {
      "post": {
        "operationId": "runs-sync-brilliant_gum-spotify-insights-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/brilliant_gum~spotify-insights-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-brilliant_gum-spotify-insights-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",
            "type": "array",
            "description": "Spotify URLs of artists, albums or tracks to scrape. Accepts open.spotify.com links and spotify: URIs. Leave empty if you use 'Search queries' instead.",
            "items": {
              "type": "string"
            }
          },
          "followAlbums": {
            "title": "Follow albums",
            "type": "boolean",
            "description": "For each artist URL, also crawl every full album and return per-track play counts.",
            "default": false
          },
          "followSingles": {
            "title": "Follow singles",
            "type": "boolean",
            "description": "For each artist URL, also crawl every single / EP.",
            "default": false
          },
          "followPopularReleases": {
            "title": "Follow popular releases",
            "type": "boolean",
            "description": "For each artist URL, also crawl Spotify's curated 'popular releases'.",
            "default": false
          },
          "scrapePreviewUrls": {
            "title": "Scrape 30s preview URLs",
            "type": "boolean",
            "description": "Include 30-second audio preview URLs for tracks (alongside, not instead of, play counts).",
            "default": false
          },
          "searchQueries": {
            "title": "Search queries (no URL needed)",
            "type": "array",
            "description": "NEW: scrape by keyword instead of URL. Each query is searched on Spotify and the top results are scraped. Pair with 'Search type' and 'Max search results'.",
            "items": {
              "type": "string"
            }
          },
          "searchType": {
            "title": "Search type",
            "enum": [
              "artist",
              "album",
              "track",
              "playlist",
              "all"
            ],
            "type": "string",
            "description": "Which entity type to return for 'Search queries'.",
            "default": "artist"
          },
          "maxSearchResults": {
            "title": "Max results per search query",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "How many top results to scrape per search query.",
            "default": 5
          },
          "includeRelatedArtists": {
            "title": "Include related artists ('Fans also like')",
            "type": "boolean",
            "description": "NEW: add the related-artists graph to each artist record. Solves the #1 missing-field complaint.",
            "default": false
          },
          "relatedArtistsDepth": {
            "title": "Related-artists crawl depth",
            "minimum": 0,
            "maximum": 3,
            "type": "integer",
            "description": "0 = only list related artists on the record. 1+ = also scrape those related artists as their own records (graph crawl). Use with care, expands runs quickly.",
            "default": 0
          },
          "includeDiscoveredOnPlaylists": {
            "title": "Include 'Discovered On' playlists",
            "type": "boolean",
            "description": "NEW: which editorial/user playlists are driving an artist's streams (playlist attribution).",
            "default": false
          },
          "includePlaylists": {
            "title": "Resolve playlist contents",
            "type": "boolean",
            "description": "NEW: for playlist URLs / search results, return full track listing, owner, and follower count (paginated past 100 tracks).",
            "default": false
          },
          "includeLyrics": {
            "title": "Include lyrics",
            "type": "boolean",
            "description": "NEW: time-synced lyrics per track (requires a valid 'sp_dc cookie').",
            "default": false
          },
          "includePodcasts": {
            "title": "Include podcasts / episodes",
            "type": "boolean",
            "description": "NEW: resolve show & episode URLs (show metadata + episode list, episode metadata).",
            "default": false
          },
          "includeAnalytics": {
            "title": "★ Include deep analytics block",
            "type": "boolean",
            "description": "BONUS: per-artist analytics — engagement/loyalty rate, top-track concentration, estimated royalty revenue range, discovery reach, and momentum (from history). Turns raw numbers into decisions.",
            "default": true
          },
          "includeContactInfo": {
            "title": "★ Extract contact info (lead-gen)",
            "type": "boolean",
            "description": "BONUS: emails (from bio) + categorized social links (Instagram/TikTok/YouTube/…) + website. Solves the marketer 'who do I contact' pain that competitors sell separately.",
            "default": true
          },
          "includeAppearsOn": {
            "title": "Include 'Appears On' & 'Featuring'",
            "type": "boolean",
            "description": "BONUS: releases the artist appears on and playlists/releases featuring them — fuller discography graph.",
            "default": false
          },
          "includeConcerts": {
            "title": "Include concerts / tour dates (best-effort)",
            "type": "boolean",
            "description": "BONUS: upcoming concerts (venue, city, date). Note: Spotify gates most concert data behind a logged-in session, so anonymous runs often return an empty list.",
            "default": false
          },
          "enrichRelatedArtists": {
            "title": "Enrich related artists with monthly listeners",
            "type": "boolean",
            "description": "BONUS: fetch monthly listeners + rank for each related artist (adds one request per related artist).",
            "default": false
          },
          "writePlayCountsCsv": {
            "title": "Write play_counts.csv",
            "type": "boolean",
            "description": "BONUS/compat: also emit a flat play_counts.csv (artist_url, artist_name, album_url, album_name, track_url, track_name, play_count) to the key-value store, matching the original actor.",
            "default": false
          },
          "enableHistory": {
            "title": "★ Enable historical tracking (trends & velocity)",
            "type": "boolean",
            "description": "THE killer feature: persist a timestamped snapshot every run into a named dataset, then compute deltas (daily stream change) and stream velocity vs the previous run. Run this actor on a schedule to build the time-series Spotify never gives you.",
            "default": false
          },
          "historyDatasetName": {
            "title": "History store name",
            "type": "string",
            "description": "Named key-value store / dataset to persist snapshots into. Reused across scheduled runs to compute trends. Defaults to 'spotify-history'.",
            "default": "spotify-history"
          },
          "spDcCookie": {
            "title": "sp_dc cookie (for lyrics)",
            "type": "string",
            "description": "Value of the 'sp_dc' cookie from a logged-in open.spotify.com session. Only needed for lyrics. Stored as a secret."
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Optional. Proxies are included and configured automatically — leave this empty unless you want to use your own."
          },
          "maxConcurrency": {
            "title": "Max concurrency",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "Parallel request workers. Keep low (3-5) to avoid 429s.",
            "default": 4
          },
          "minDelayMs": {
            "title": "Min delay between requests (ms)",
            "minimum": 0,
            "maximum": 10000,
            "type": "integer",
            "description": "Throttle to look human and avoid rate limits.",
            "default": 350
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}