Overview
This document serves as a guide to assist Music Analytics API users with onboarding and authorizing new users, privacy requirements, and endpoint descriptions. Check out some frequently asked questions for more information.

Used to assist Music Analytics API users with onboarding and authorizing new users, privacy requirements, and endpoint descriptions.
This document serves as a guide to assist Music Analytics API users with onboarding and authorizing new users, privacy requirements, and endpoint descriptions. Check out some frequently asked questions for more information.
All reports downloaded using Reporter will migrate to the Music Analytics API report endpoint. Partners must migrate to the API to replace reporting workflows.
The new Apple Music Disguised Listening Report providing reporting on detected stream manipulation activity, identifying instances where your content was used to disguise or cover the manipulation of other content, is now available and accessible through its new endpoint.
The Music Analytics API Engagement and Overlap endpoints are now available to all direct Apple Music partners who have delivered content.
A new group by option lets you partition your audience by equal listener groups (percentile-based) or logarithmic play-count ranges, revealing who your most engaged listeners are and how that engagement is distributed across your catalog.
You can now filter and group your analytics by International Standard Recording Code (ISRC) and Universal Product Code (UPC), enabling precise insights at the individual recording and product level, and making it easy to analyze performance across shared recordings, compilations, and different releases of your catalog.
You can now retrieve ranked lists of your top-performing songs, albums, or artists by specifying a result limit, and sort results by play count or unique listeners in ascending or descending order. This can be combined with existing filters such as date range, storefront, and device type.
Release Dates have been added to the Audience Engagement and Audience Overlap endpoints of the Music Analytics API. Filter by content that was released between a start and end date and compare your newest content to your catalog content. Group by Release Dates to get the exact date your content was released. There is no change to your Music Analytics API version.
Genres and subgenres for albums and songs have been added to the Audience Engagement and Audience Overlap endpoints of the Music Analytics API. Filter and group by your album or song genre and subgenre to better understand content performance and benchmarking across genres. There is no change to your Music Analytics API version.
Detailed Results has been added to the Audience Engagement endpoint of the Music Analytics API. When demographic data is not being used in this endpoint, you’ll automatically receive exact counts instead of rounded figures. Rounding will be enabled when using age, gender, or consumer city in the API call. There is no change to your Music Analytics API version.
Asynchronous Batch Processing has been added to all Audience endpoints of the Music Analytics API. There is no change to your Music Analytics API version.
Container Sub-Types for Apple Music Mood Stations have been added to all Audience endpoints of the Music Analytics API. There is no change to your Music Analytics API version.
Group By date dimension has been added to all Audience endpoints in the Music Analytics API. There is no change to your Music Analytics API version.
Add new users to the Music Analytics API by taking the following steps:
Click Users and Access in iTunes Connect.

Click Keys.

To add a new user, click the plus sign (+).

When the Generate API Key dialog appears, enter the user’s name (for example, Johnny Appleseed) and choose between Admin or Technical in the Access field. At this time, there is no difference between the two roles.


Click Generate. The new user will appear in the Active list.


If the API Key hasn’t been downloaded, click the Download API Key link, store it in a safe location, and back up as needed.
NOTE: Unique to the user or shared group (like a generic team email), you can only download an API Key one time. If a user key has been lost or compromised, the user should be removed and added as a new user again.
Once you’ve generated or downloaded your API Key, return to the Keys page to find an Issuer ID. This 36-character alphanumeric sequence is unique to the content provider and is required for users to log in to the Music Analytics API.

Once a user is added to the Music Analytics API tool, ensure they appear in the Keys Active list and have access to the following upon executing:
The musicanalytics-utils-0.2.0.jar file
NOTE: Before using this script, make sure you have Java 8.0 or later, and the Java Development Kit (JDK) installed.
A separate private key file (for example, AuthKey_1234567890.p8)
Issuer ID (Located above the Active list, this 36-character alphanumeric sequence is unique to the content provider and is required for users to log in to the Music Analytics API.)
Once you have all of the items above, use a command prompt program (for example, Terminal in macOS or equivalent third-party program), navigate to the file directory, and complete the following steps:
Execute the musicanalytics-utils-0.2.0.jar file by typing: java -jar musicanalytics- utils-0.2.0.jar -c {insert value for Issuer ID} -f {insert file name for your private key file}. You will receive a JSON Web Token (JWT), a string of 270 case-sensitive characters that will require testing.
NOTE : The JWT will only be available for 20 minutes. If the JWT expires, complete step 1 again to renew the token.
Test the JWT by generating a curl request (for example, curl -H “Authorization: Bearer {insert full JWT} “) https://musicanalytics.apple.com/v4/queries.
If successful, you will receive a 200 HTTP status code that will enable users to access the Music Analytics API.
To better understand the Music Analytics API, we suggest reviewing examples of requests and responses, as well as the API schema. You can issue authenticated GET requests to see these. More information is available in Endpoint Descriptions.
The Music Analytics API provides results once listeners or play counts cross the minimum thresholds. Attempts to de-anonymize data from the product are strictly prohibited and may result in suspension or revocation of access.
Every endpoint will have a GET and POST function. The base URL for every function is https://musicanalytics.apple.com/v4/queries/.
Only authorized users will receive and have access to the GET or POST function results.
GET functions provide the schema of returned fields and applicable ranges that can be used.
POST functions provide live results based on the criteria you select.
If a user receives a response other than a 200 HTTP status code, they are likely not authorized and should perform the authentication steps above.
Upon successful authorization to the Music Analytics API, we highly suggest performing GET requests on all available query paths. The response will include available dimensions, example queries, and more.
GET/POST: https://musicanalytics.apple.com/v4/queries/audience-engagement
Allows queries for specific containers where listeners discovered content.
This buckets aggregated counts of unique listeners and plays for a specified artist, album, or song alongside optional fields of where and how the listener engaged with the content on Apple Music. Examples include End Reason Type, Source of Stream, Container Sub-Type, and more.
GET/POST: https://musicanalytics.apple.com/v4/queries/audience-overlap
Provides counts of listeners and plays by dimension, and allows queries for specific containers where listeners discovered content. It cohorts listeners, analyzes an artist, album, or song, and compares their listenership against two periods of time.
Field Name | Common Field Name | Definition | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
primary_audience_lc | Primary Audience Listener Count | The total cohorted count of listeners who meet the criteria specified in time period 1 | |||||||||
primary_difference_lc | Primary Difference Listener Count | The total cohorted count of listeners who meet the criteria specified in time period 1 and do not meet the criteria specified in time period 2 | |||||||||
captured_lc | Captured Listener Count | The total cohorted count of listeners who meet the criteria specified in time period 1 and meet the criteria specified in time period 2 | |||||||||
secondary_audience_lc | Secondary Audience Listener Count | The total cohorted count of listeners who meet the criteria specified in time period 2 | |||||||||
primary_audience_pc | Primary Audience Play Count | The total count of plays from the Primary Audience Listener Count pertaining to time period 1 | |||||||||
primary_difference_pc | Primary Difference Play Count | The total count of plays from the Primary Difference Listener Count pertaining to time period 1 | |||||||||
primary_captured_pc | Primary Captured Play Count | The total count of plays from the Captured Listener Count pertaining to time period 1 | |||||||||
secondary_captured_pc | Secondary Captured Play Count | The total count of plays from the Captured Listener Count pertaining to time period 2 | |||||||||
secondary_audience_pc | Secondary Audience Play Count | The total count of plays from the Secondary Audience Listener Count pertaining to time period 2 | |||||||||
POST to audience-engagement or audience-overlap and get your results at a later time. These requests will only allow a single query to process at a time. When a query is already running, a new request will fail with a 400 response code and include a message containing the query ID that is occupying the compute warehouse. The macro discovered-in parameter “first-stream-since” is restricted to three years from the end of your “played-in” end date.
Endpoint | Type | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
/request | POST | Request to run the process in the background. This will return a query ID to retrieve your results. | |||||||||
/status?queryId= | GET | Request the status of your results. Results include: In Progress Failed Cancelled Ready Expired | |||||||||
/get?queryId= | GET | Request to return your results once they are ready. Results are available for 24 hours. | |||||||||
/cancel?queryId= | GET | Request to cancel an API call. | |||||||||
Macro discovered-in highlights growth in discovery and re-engagement. This feature creates the ability to search across a partner’s entire catalog to identify the unexpected or unknown content experiencing a spike, identify the source of discovery across their catalog, and understand the impact of editorial or marketing efforts on the discovery of their content.
A new parameter “discovered_entity” performs the discovery check for a listener based on the entity type (artist, album, or song). The field is required within the “discovered_in” definition for macro queries and must be accompanied by a matching “group_by” entity.
Field | Description | Schema | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
discovered_entity | Modifies the discovered in filter to compute audiences on the entity (artist, album, or song). This field takes entity names as arguments, and must be accompanied by the same name in the group_by clause. When discovered_entity is included, entity filters are optional (i.e., macro + discovered_in becomes valid). Results with discovered_entity will strictly compute discovery audiences per every entity. For example, when using song_id, every song_id grouping will only contain listeners who have discovered that content specifically. Example values: song_id, artist_id, album_id. | "discovered_entity": {"type": "string",} | |||||||||
The limits on the number of entities you can specify have been increased. This feature increases the amount of entities to 5,000 artists, 10,000 albums, and 10,000 songs. Macro queries can now look back 365 days, increased from 31 days in the standard API queries.
GET/POST: https://musicanalytics.apple.com/v4/city
Provides a reference of consumer_city (IDs) to consumer_city_name mappings. It also gives users the ability to filter by a specific consumer_city ID to obtain the consumer_city_name of the input values.
GET: https://musicanalytics.apple.com/reports/flagged-streams/v3
Provides standard reporting fields for all content streams that have been flagged.
GET: https://musicanalytics.apple.com/reports/disguised-listening-streams/v1
Provides reporting on detected stream manipulation activity, identifying instances where your content was used to disguise or cover the manipulation of other content.
GET: https://musicanalytics.apple.com/reports/in-review-content/v2
Provides standard reporting fields for albums currently flagged for review.
GET: https://musicanalytics.apple.com/reports/excluded-streams/v2
Provides a monthly summary of all content that has been excluded from royalty-bearing reporting and calculations.
Every report has a GET function. The base URL for every function is https://musicanalytics.apple.com/reports/. Every GET and download request requires the JWT to be added to the header. Only authorized users will receive and have access to the GET function results.
A single request returns one slice of reporting: one report, one vendor, one reporting date, and one granularity. A slice is delivered as one or more gzipped tab-separated parts. The GET function returns a manifest describing the slice — how many parts it has, how large each one is, and where to download it. Retrieving a report therefore takes two steps: request the manifest, then download each part it names.
If a user receives a response other than a 200 HTTP status code, they may not be authorized and should perform the authentication steps above.
GET: https://musicanalytics.apple.com/reports/<report-name>/v1
Provides the manifest for one slice of a report. There is one path per report.
Parameter | Required | Definition | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
sap_vendor_id | Always | The vendor whose report is requested. | |||||||||
rptg_date | Always | The reporting date, formatted YYYY-MM-DD. For a monthly report, the month’s last date; for a weekly report, the week’s last day. | |||||||||
granularity | Only when the report serves more than one. | Daily, weekly, monthly or yearly. A report that serves a single granularity supplies its own value, so the parameter can be omitted, but if it is sent, it must match. Reports such as summary-preorder serve all four and must be included. | |||||||||
Example request
curl -X GET "https://musicanalytics.apple.com/reports/summary-streams/v1?sap_vendor_id=80012345&rptg_date=2026-06-10" -H "Authorization: Bearer {insert full JWT}"
Each part is downloaded from its own URL as given in the manifest. The bytes returned are a gzipped tab-separated file. This request requires your JWT to be added to the header for authorization.
curl -fOJ "<download URL>" -H "Authorization: Bearer {insert full JWT}"
File name format
<ReportName>_<sap_vendor_id>_<date>_[part-of-total].tsv.gz
AppleMusic_SummaryStreams_80012345_20260610_[1-3].tsv.gz
The part suffix is always present. A slice consisting of a single file reads [1-1], so one pattern matches whatever the part count. Dates are stamped YYYYMMDD, monthly reports are stamped YYYYMMDD, and .tsv.gz is a gzipped tab-separated file.
Example response
{
"report": { "type": "summary-streams", "vendor": "80012345",
"date": "2026-06-10", "granularity": "daily" },
"format": "gzip-manifest",
"total_parts": 3,
"total_bytes": 53620026,
"total_rows": 4571136,
"parts": [
{ "index": 1,
"size_bytes": 17873342,
"row_count": 1523712,
"filename": "AppleMusic_SummaryStreams_80012345_20260610_[1-3].tsv.gz",
"md5": "9f2a1c4e7b8d0356a1f4e2c9b7d5308a",
"url": "<download URL>" },
{ "index": 2, "...": "..." },
{ "index": 3, "...": "..." }
]
}
Manifest fields
Field Name | Common Field Name | Definition | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
report | Report | The slice this manifest describes, echoing back the request. | |||||||||
total_parts | Total Parts | The number of files that make up the whole slice. It follows data volume and can change if the slice is produced again, so it should be read rather than assumed. | |||||||||
total_bytes | Total Bytes | Compressed size of the whole slice. | |||||||||
total_rows | Total Rows | Data rows in the whole slice, excluding header lines. | |||||||||
parts[].index | Part Index | Part number, starting at 1. | |||||||||
parts[].size_bytes | Part Size | Compressed size of this file. | |||||||||
parts[].row_count | Part Row Count | Data rows in this file, excluding its header line. | |||||||||
parts[].filename | Part File Name | The name the file is saved as. | |||||||||
parts[].md5 | Part MD5 | MD5 of this file, for verifying the download. | |||||||||
parts[].url | Part URL | Where to download this file. | |||||||||
Apple Music Content Report
Request URL
https://musicanalytics.apple.com/reports/content/v1?sap_vendor_id=80012345&rptg_date=2026-06-10
Apple Music Summary Streams Report
Request URL
https://musicanalytics.apple.com/reports/summary-streams/v1?sap_vendor_id=80012345&rptg_date=2026-06-10
Apple Music Container Summary Report
Request URL
https://musicanalytics.apple.com/reports/container-summary/v1?sap_vendor_id=80012345&rptg_date=2026-06-10
Apple Music Library Events Report
Request URL
https://musicanalytics.apple.com/reports/library-events/v1?sap_vendor_id=80012345&rptg_date=2026-06-10
Apple Music Total Library Adds Report
Request URL
https://musicanalytics.apple.com/reports/total-library-adds/v1?sap_vendor_id=80012345&rptg_date=2026-06-10
Apple Music Editorial Playlist Adds Report
Request URL
https://musicanalytics.apple.com/reports/editorial-playlist-adds/v1?sap_vendor_id=80012345&rptg_date=2026-06-10
Apple Music Artist Demographics Report
Request URL
https://musicanalytics.apple.com/reports/artist-demographics/v1?granularity=daily&sap_vendor_id=80012345&rptg_date=2026-06-10
Apple Music Content Demographics Report
Request URL
https://musicanalytics.apple.com/reports/content-demographics/v1?granularity=daily&sap_vendor_id=80012345&rptg_date=2026-06-10
iTunes Detailed Pre-Order Report
Request URL
https://musicanalytics.apple.com/reports/detailed-preorder/v1?sap_vendor_id=80012345&rptg_date=2026-06-10
iTunes Summary Pre-Order Report
Request URL
https://musicanalytics.apple.com/reports/summary-preorder/v1?sap_vendor_id=80012345&rptg_date=2026-06-10
iTunes Detailed Sales Report
Request URL
https://musicanalytics.apple.com/reports/detailed-sales/v1?sap_vendor_id=80012345&rptg_date=2026-06-10
iTunes Summary Sales Report
Request URL
https://musicanalytics.apple.com/reports/summary-sales/v1?sap_vendor_id=80012345&rptg_date=2026-06-10
iTunes Artist Demographics Report
Request URL
https://musicanalytics.apple.com/reports/artist-demographics-sales/v1?sap_vendor_id=80012345&rptg_date=2026-06-10&granularity=weekly
iTunes Content Demographics Report
Request URL
https://musicanalytics.apple.com/reports/content-demographics-sales/v1?sap_vendor_id=80012345&rptg_date=2026-06-10&granularity=weekly
Shazam Report
Request URL
https://musicanalytics.apple.com/reports/shazam/v1?sap_vendor_id=80012345&rptg_date=2026-06-10