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.

What’s New In This Version

November 2026

  • All reports downloaded using Reporter will migrate to the Music Analytics API report endpoint. Partners must migrate to the API to replace reporting workflows.

September 2026

  • 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.

July 2026

  • 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.

June 2026

  • 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.

May 2026

  • 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.

February 2026

  • 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.

January 2026

  • 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.

November 2025

  • 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.

July 2025

  • 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.

June 2025

  • 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.

Onboarding New Users

Add new users to the Music Analytics API by taking the following steps:

  1. Click Users and Access in iTunes Connect.

    iTC Homepage
  2. Click Keys.

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

    User and Access Keys
  4. 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.

    Generate API Key
    Johnny Appleseed Admin
  5. Click Generate. The new user will appear in the Active list.

    Johnny Appleseed Active
    Download API Key

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.

Keys and Issuer ID

Authorization

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:

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:

  1. 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.

  2. Test the JWT by generating a curl request (for example, curl -H “Authorization: Bearer {insert full JWT} “) https://musicanalytics.apple.com/v4/queries.

  3. 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.

Privacy Requirements

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.

Endpoint Descriptions

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.

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.

Audience Engagement

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.

Audience Overlap

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

Asynchronous Batch Processing

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

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",}

Increased Query Limits

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.

City

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.

Flagged Streams

GET: https://musicanalytics.apple.com/reports/flagged-streams/v3

Provides standard reporting fields for all content streams that have been flagged.

Disguised Listening

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.

In Review Content

GET: https://musicanalytics.apple.com/reports/in-review-content/v2

Provides standard reporting fields for albums currently flagged for review.

Excluded Streams

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.

Reports Endpoint

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.

Report Manifest

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}"

Downloading a Part

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.

Reports

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