How to request your Spotify archive and import it into Harmony for deeper analytics.

Getting & Importing the Spotify Package

Harmony’s advanced statistics (e.g. year-over-year trends, forgotten gems, historical rankings) require data that the public Spotify API does not expose. You can supply this information yourself by uploading the Extended Streaming History package Spotify provides on request.

The import feature is optional, Harmony still works without it, but you’ll unlock richer insights once the package is uploaded.

Requesting Your Package

Open the Spotify Privacy page on the Spotify website.
Scroll to Download your data and edit the "Download your data" section as on the image:

Spotify Privacy page

Click Request data.
Confirm your request via email.
After clicking "Request data," Spotify will send you a confirmation email. Open the email and follow the instructions to confirm your data request.
Wait for your data to be prepared.
Spotify will process your request, this can take up to 30 days, but it often arrives sooner. You’ll receive another email when your archive is ready for download.
Download your Spotify data ZIP file.
The email will include a download link, usually for a file named my_spotify_data.zip. Do not unzip or rename its internal files, Harmony requires the original ZIP format for import.

The download link from Spotify expires after 14 days. Be sure to save the ZIP file locally until you’ve imported it into Harmony.

Uploading to Harmony

Open Package in the sidebar.
Click Choose file and select the ZIP you downloaded.
Harmony validates the structure and queues the archive for processing.
You’ll receive a toast when the import is complete (usually < 1 min).

What Gets Imported?

We import all JSON files inside the ZIP that match the pattern Streaming_History_Audio_*.json.

Re-Uploading New Data

When you upload a new package, Harmony will first remove your previous archive and then import all tracks from the new ZIP.

Troubleshooting

There are several types of data packages Spotify may provide, but only the "Extended streaming history data" package contains the correct files for importing into Harmony. The other packages are not eligible for import.

Type of data	Description	Data preparation time
Account data	Basic account info, one year of streaming data	~ 5 days
Technical log information	Technical logs Spotify has collected about you	Up to 30 days
Extended streaming history data	Lifetime streaming history information	Up to 30 days (avg. 2–3 weeks)

Only the Extended streaming history data package includes the correct files to import to Harmony. If you received a different package, it cannot be imported. We recommend checking the email from Spotify to ensure you have the correct package before uploading.

Issue	Fix
"Invalid package structure"	Make sure you selected the ZIP file you received from Spotify, not an extracted folder. Only the Extended streaming history data ZIP is supported. If you uploaded a different package, please request the correct one from Spotify.
Import stuck at 0 %	Reload the page and try again. If the issue persists, create an issue on the GitHub.
Tracks show as "Unknown"	Wait for the nightly metadata sync; Harmony back-fills missing IDs.

Once imported, refresh your dashboard to explore new historical insights!