# My Spotify History Data (`onescales/spotify-history`) Actor View your complete Spotify play history in a report and analyze how much time you've spent with your favorite artists and songs! This app processes your Spotify stats data, export files and delivers detailed insights into your listening habits so you can view in Excel or Google Sheets (csv) & image. - **URL**: https://apify.com/onescales/spotify-history.md - **Developed by:** [One Scales](https://apify.com/onescales) (community) - **Categories:** Automation, Other, Social media - **Stats:** 424 total users, 3 monthly users, 42.5% runs succeeded, 4 bookmarks - **User rating**: 2.44 out of 5 stars ## Pricing Pay per usage This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.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/platform/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 View your complete Spotify play history and analyze how much time you've spent with your favorite artists and songs! This app processes your Spotify data export files and delivers detailed statistics and insights into your listening habits so you can view and explore the data in Excel or Google Sheets (CSV format). **📌 Note**: This app analyzes **Streaming History** and **Extended Streaming History** files only. (ONLY Upload files named Streaming_History....) It does not process other Spotify export data types (like playlists, library, or user data). [![Watch the video](https://img.youtube.com/vi/XsPV1OHjqYE/maxresdefault.jpg)](https://www.youtube.com/watch?v=XsPV1OHjqYE) ### What You Get - **Overall Statistics**: Total plays, listening time, date range, and daily averages - **Top Artists**: Your most-played artists with play counts and listening hours (unlimited or set your own limit) - **Top Tracks**: Your favorite songs ranked by play count (unlimited or set your own limit) - **Timeline Data**: When you discovered artists and tracks - **Detailed Metrics**: Play counts, percentages, and time breakdowns - **All in One View**: Single "My Data" tab with summary, artists, and tracks all together ### How to Use #### Step 1: Get Your Spotify Data 1. Go to [Spotify Privacy Settings](https://www.spotify.com/account/privacy/) 2. Scroll down to "Download your data" 3. Select either: - **"Account data"**: Faster delivery (usually a few days, sometimes just 1 day), includes full metadata - **"Extended streaming history"**: Can take up to 30 days (but sometimes arrives in 1 day), more complete history 4. Wait for Spotify to email you 5. Download and unzip the files 6. Look for files named `StreamingHistory0.json`, `StreamingHistory1.json`, etc. #### Step 2: Upload Your Files 1. In the Apify actor input form, find the **file upload fields**: - 📁 Spotify JSON File 1 (required) - 📁 Spotify JSON File 2-5 (optional) 2. For each file: - Click on the upload field - Either **upload the JSON file** from your computer, OR - **Provide a URL** to the JSON file if hosted online 3. Upload all your StreamingHistory files (you can use up to 5 files) 4. (Optional) Configure additional settings like date filters 5. Click "Start" #### Step 3: View Your Results Check the **Dataset** tab to see the **"My Data"** view with: - 📊 **Row 1**: Summary of your listening habits - 🎤 **Next rows**: All your top artists (ranked by plays) - 🎵 **Final rows**: All your top tracks (ranked by plays) ### Output Fields | Field | Description | |-------|-------------| | **rank** | Ranking position (0 = summary, 1+ = most played) | | **name** | Artist or track name | | **type** | Summary, Artist, or Track | | **image** | Link to Infographic image of summary of your data | | **playCount** | Number of times played | | **totalMinutes** | Total minutes listened | | **totalHours** | Total hours listened | | **totalDays** | Total days listened (summary only) | | **percentage** | Percentage of your total listening time | | **firstPlayed** | Date you first played this | | **lastPlayed** | Most recent play date | | **daysCovered** | Number of days between first and last play (summary only) | | **avgMinutesPerDay** | Average minutes per day (summary only) | | **uniqueArtists** | Total unique artists (summary only) | | **uniqueTracks** | Number of unique tracks (summary or for each artist) | | **trackName** | Track name (tracks only) | | **artistName** | Artist name (tracks only) | ### Input Options #### Required - **Spotify JSON File 1**: Upload your first StreamingHistory JSON file #### Optional Files - **Spotify JSON File 2-5**: Upload additional StreamingHistory files (up to 5 total) #### Optional Filters - **Start Date**: Filter plays from this date onwards (YYYY-MM-DD format). Leave empty for all data. - **End Date**: Filter plays up to this date (YYYY-MM-DD format). Leave empty for all data. - **Minimum Play Time**: Only count songs played for at least X seconds (helps filter out skips). **Leave empty to include all plays** (no filtering). - **Maximum Artists to Export**: Limit the number of top artists in results. Leave empty for unlimited. Recommended: 500 - **Maximum Tracks to Export**: Limit the number of top tracks in results. Leave empty for unlimited. Recommended: 500 ### Tips - **Multiple Files**: Upload all your StreamingHistory files (up to 5) to get complete analysis - **No Default Filtering**: By default, ALL plays are included. Set minimum play time only if you want to filter out skips - **Export Limits**: For very large datasets, use the max artists/tracks settings to limit output size and improve performance - **Filter Skips**: Set minimum play time to 60+ seconds to filter out skipped songs - **Date Ranges**: Use date filters to compare different time periods (e.g., 2023 vs 2024) - **Download Results**: Export the dataset as CSV/JSON/Excel for further analysis ### Troubleshooting **Most plays show as "Unknown" artist/track** - Some Spotify exports don't include full metadata - This can happen with certain export types or older data - The actor will still calculate time statistics correctly even without full metadata - If you need complete metadata, try requesting a different export type from Spotify **"Failed to fetch file" or "File not found"** - Make sure you uploaded the correct JSON files from Spotify - Files should be named `StreamingHistory*.json` from your Spotify export - If providing URLs, ensure they are publicly accessible - Try re-uploading the files **"JSON data must be an array"** - Your file might be corrupted or in the wrong format - Make sure you're uploading the actual StreamingHistory JSON files from Spotify - Content should start with `[` and contain streaming history records **"Some plays are missing"** - Check your date filters (Start Date / End Date) - Check if you set a minimum play time (plays shorter than this are excluded) - Spotify only provides data from when you started using the service **Output is too large / Actor times out** - Use the "Maximum Artists to Export" and "Maximum Tracks to Export" settings - Try setting both to 500 for a reasonable dataset size - Or filter by date range to analyze smaller time periods ### Privacy This actor runs entirely in your Apify account. Your Spotify data is: - Only processed during the actor run - Stored only in your Apify dataset ### Roadmap Here are the future features we will be developing. If you have any additional suggestions, contact us at https://docs.google.com/forms/d/e/1FAIpQLSfsKyzZ3nRED7mML47I4LAfNh_mBwkuFMp1FgYYJ4AkDRgaRw/viewform?usp=dialog - Support Stream History File for Podcasts (i.e. StreamingHistory_podcast_0.json) - Support Playlists (i.e. Playlist1.json) ### Support Have Questions or Need Additional Features? We're here to support you! Whether you need help with setup, have questions about interpreting results, or want to request additional features for Pitches Pro, we've got you covered. **Contact Us**: Just fill out the form at https://docs.google.com/forms/d/e/1FAIpQLSfsKyzZ3nRED7mML47I4LAfNh_mBwkuFMp1FgYYJ4AkDRgaRw/viewform?usp=dialog, and we'll try our best to help as quickly as possible. # Actor input Schema ## `file1` (type: `string`): Upload your first StreamingHistory JSON file or provide a URL ## `file2` (type: `string`): Upload your second StreamingHistory JSON file or provide a URL ## `file3` (type: `string`): Upload your third StreamingHistory JSON file or provide a URL ## `file4` (type: `string`): Upload your fourth StreamingHistory JSON file or provide a URL ## `file5` (type: `string`): Upload your fifth StreamingHistory JSON file or provide a URL ## `dateRangeStart` (type: `string`): Filter data from this date onwards (YYYY-MM-DD format). Leave empty for all data. ## `dateRangeEnd` (type: `string`): Filter data up to this date (YYYY-MM-DD format). Leave empty for all data. ## `minimumPlayTime` (type: `integer`): Only count songs played for at least this many seconds (helps filter out skips). Leave empty to include all plays. ## `maxArtists` (type: `integer`): Maximum number of top artists to include in results. Leave empty for unlimited. Recommended: 500 ## `maxTracks` (type: `integer`): Maximum number of top tracks to include in results. Leave empty for unlimited. Recommended: 500 ## Actor input object example ```json { "file1": "https://cdn.shopify.com/s/files/1/0698/1274/8583/files/Streaming_History_TEST2.json" } ```` # Actor output Schema ## `analysisResults` (type: `string`): View your listening statistics, infographic, top artists, and top tracks # 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 = { "file1": "https://cdn.shopify.com/s/files/1/0698/1274/8583/files/Streaming_History_TEST2.json" }; // Run the Actor and wait for it to finish const run = await client.actor("onescales/spotify-history").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 = { "file1": "https://cdn.shopify.com/s/files/1/0698/1274/8583/files/Streaming_History_TEST2.json" } # Run the Actor and wait for it to finish run = client.actor("onescales/spotify-history").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 '{ "file1": "https://cdn.shopify.com/s/files/1/0698/1274/8583/files/Streaming_History_TEST2.json" }' | apify call onescales/spotify-history --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=onescales/spotify-history", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "My Spotify History Data", "description": "View your complete Spotify play history in a report and analyze how much time you've spent with your favorite artists and songs! This app processes your Spotify stats data, export files and delivers detailed insights into your listening habits so you can view in Excel or Google Sheets (csv) & image.", "version": "0.1", "x-build-id": "K40T5poI550yW8dhb" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/onescales~spotify-history/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-onescales-spotify-history", "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/onescales~spotify-history/runs": { "post": { "operationId": "runs-sync-onescales-spotify-history", "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/onescales~spotify-history/run-sync": { "post": { "operationId": "run-sync-onescales-spotify-history", "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": [ "file1" ], "properties": { "file1": { "title": "📁 Spotify JSON File 1", "type": "string", "description": "Upload your first StreamingHistory JSON file or provide a URL" }, "file2": { "title": "📁 Spotify JSON File 2", "type": "string", "description": "Upload your second StreamingHistory JSON file or provide a URL" }, "file3": { "title": "📁 Spotify JSON File 3", "type": "string", "description": "Upload your third StreamingHistory JSON file or provide a URL" }, "file4": { "title": "📁 Spotify JSON File 4", "type": "string", "description": "Upload your fourth StreamingHistory JSON file or provide a URL" }, "file5": { "title": "📁 Spotify JSON File 5", "type": "string", "description": "Upload your fifth StreamingHistory JSON file or provide a URL" }, "dateRangeStart": { "title": "Start Date", "pattern": "^$|^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "Filter data from this date onwards (YYYY-MM-DD format). Leave empty for all data." }, "dateRangeEnd": { "title": "End Date", "pattern": "^$|^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "Filter data up to this date (YYYY-MM-DD format). Leave empty for all data." }, "minimumPlayTime": { "title": "Minimum Play Time (seconds)", "minimum": 0, "maximum": 300, "type": "integer", "description": "Only count songs played for at least this many seconds (helps filter out skips). Leave empty to include all plays." }, "maxArtists": { "title": "Maximum Artists to Export", "minimum": 0, "type": "integer", "description": "Maximum number of top artists to include in results. Leave empty for unlimited. Recommended: 500" }, "maxTracks": { "title": "Maximum Tracks to Export", "minimum": 0, "type": "integer", "description": "Maximum number of top tracks to include in results. Leave empty for unlimited. Recommended: 500" } } }, "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 } } } } } } } } } } ```