Amazon Music Web API

Web API Tracks V1.0

Important: These Amazon Music APIs are currently in a closed Beta. To join the waitlist, select 'Music Developers' in the contact us form here.

Important: These Amazon Music documents are in preview status. Be aware that content may change. Please use the developer forum for any questions or comments.

Tracks

Methods for retrieving meta-data for individual music tracks. This does not include podcast episodes. Please use the Podcast endpoints to retrieve those.

Get Tracks
Get Multiple Tracks
Add Track to Current User's Library
Delete Track From Current User's Library
Get Current User's Liked Tracks
Update Current User's Liked Tracks

Get Tracks

GET

/tracks/{id}

Authorization Scope: [music::catalog]

Get the Amazon Music catalog meta-data for a single track by track ID. This includes the name of the track title, the album, the artist, and more.

Path Parameters

Name	Data Type	Required	Description
id	string	Yes	The ID of the track to be retrieved.

Query Parameters

Name	Data Type	Required	Description
mediaType	string	No	Type can be either AUDIO or VIDEO.

Example

curl --request GET '<base url>/v1/tracks/B076YT2CBT'
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>'

Response

Amazon Music response object containing:

Name	Data Type	Required	Description
track	Track	No	Data about the Amazon Music track

Example

(Some lines omitted for brevity)

{
  "data": {
    "track": {
      "id": "B076YT2CBT",
      "globalAsin": "B076YT2CBT",
      "title": "Happy (From \"Despicable Me 2\")",
      "shortTitle": "Happy (From \"Despicable Me 2\")",
      "duration": 232,
      "album": {
        "id": "B076YSK8CS",
        "title": "G I R L",
        "url": "https://music.amazon.com/albums/B076YSK8CS"
      },
      "releaseDate": "2013-06-18T04:00:00.000Z",
      "isrc": "USQ4E1300686",
      "artists": [
        {
          "id": "B000QJPQTA",
          "name": "Pharrell Williams",
          "url": "https://music.amazon.com/artists/B000QJPQTA"
        }
      ],
      "musicTerritory": {
        "code": "US",
        "territoryName": "United States"
      },
      "market": {
        "id": "US",
        "name": "United States"
      },
      "eligibility": {
        "isDownloadable": true,
        "isPurchaseable": true,
        "isPreviewable": true,
        "isPrimeEligible": false
      },
      "parentalSettings": {
        "isKidFriendly": false,
        "hasExplicitLanguage": false
      },
      "images": [
        {
          "height": 1391,
          "width": 1400,
          "url": "https://m.media-amazon.com/images/I/81ms-ME02uL.jpg"
        },
        ...
      ],
      "label": "Columbia",
    }
  }
}

Get Multiple Tracks

GET

/tracks

Authorization Scope: [music::catalog]

Get the Amazon Music catalog meta-data for multiple tracks identified by comma-separated catalog IDs. This includes the name of the track title, the album, the artist, and more.

Query Parameters

Name	Data Type	Required	Description
ids	string	Yes	A comma-separated list of the IDs of the tracks to be retrieved. There is a maximum limit of 100 IDs.
mediaType	string	No	Type can be either AUDIO or VIDEO.

Example

curl --request GET <base url>/v1/tracks?ids=B0042GBQS8,B000VBH2R2 
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>'

Response

Amazon Music response object containing:

Name	Data Type	Required	Description
tracks	Track[]	No	Data about the Amazon Music track

Example

{
  "data": {
    "tracks": [
      {
        "id": "B0042GBQS8",
        "globalAsin": "B0042GBQS8",
        "title": "Texas Flood",
        "shortTitle": "Texas Flood",
        "duration": 160,
        "album": {
            "id": "B0042GEWCU",
            "title": "Blues for the Road, Vol. 4",
            "url": "https://music.amazon.com/albums/B0042GEWCU?ref=dm_ff_amazonmusic.webportal"
        },
        "mediaType": "AUDIO",
        "release": {
            "streetDate": "2010-09-13T00:00:00-04:00",
            "localOriginalReleaseDate": "1958-01-01"
        },
        "releaseDate": "1958-01-01T05:00:00.000Z",
        "isrc": "FR6V80879665",
        "artists": [
            {
                "id": "B000S29HEU",
                "name": "Larry Davis",
                "url": "https://music.amazon.com/artists/B000S29HEU?ref=dm_ff_amazonmusic.webportal"
            }
        ],
        "musicTerritory": {
          "code": "US",
          "territoryName": "United States"
        },

        "eligibility": {
          "isDownloadable": true,
          "isPurchaseable": true,
          "isPreviewable": true,
          "isPrimeEligible": false
        },
        "parentalSettings": {
          "isKidFriendly": false,
          "hasExplicitLanguage": false
        },
        "images": [
          {
            "height": 1391,
            "width": 1400,
            "url": "https://m.media-amazon.com/images/I/81ms-ME02uL.jpg"
          },
          {
            "height": 497,
            "width": 500,
            "url": "https://m.media-amazon.com/images/I/51ZDwgg4HFL.jpg"
          }
        ],
        "label": "Brownsville",
        "url": "https://music.amazon.com/albums/B0042GEWCU/?trackAsin=B0042GBQS8",
        "previewUrl": "https://music.amazon.com/getSampleTrack/B0042GBQS8"
      },
      {
        "id": "B000VBH2R2",
        "globalAsin": "B000VBH2R2",
        "title": "November Rain",
        "shortTitle": "November Rain",
        "duration": 537,
        "album": {
            "id": "B000VBJ504",
            "title": "Use Your Illusion I [Explicit]",
            "url": "https://music.amazon.com/albums/B000VBJ504"
        },
        "mediaType": "AUDIO",
        "release": {
            "streetDate": "1991-09-17T00:00:00-04:00",
            "localOriginalReleaseDate": "1991-09-17"
        },
        "releaseDate": "1991-09-17T04:00:00.000Z",
        "isrc": "USGF19141510",
        "artists": [
            {
                "id": "B000V63WIA",
                "name": "Guns N' Roses",
                "url": "https://music.amazon.com/artists/B000V63WIA"
            }
        ],
        "label": "Guns N Roses P&D",
        "url": "https://music.amazon.com/albums/B000VBJ504/?trackAsin=B000VBH2R2",
        "previewUrl": "https://music.amazon.com/getSampleTrack/B000VBH2R2",
      }    
    ]
  }
}

Add Track to Current User's Library

PUT

/me/library/tracks/{id}

Authorization Scope: [music::library]

Save a specified track to the current Amazon Music user’s library.

Path Parameters

Name	Data Type	Required	Description
id	string	Yes	The Amazon Music catalog ID of the track to save.

Example

curl --request PUT '<base url>/v1/me/library/tracks/B08DL2BXQC' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>'

Response

Amazon Music response object containing:

Name	Data Type	Required	Description
saveTrack	SaveTrackResponse	No	Data about the saved Amazon Music track

Example

{
  "data": {
   "saveTrack": {
      "track": {
        "id": "B08DL2BXQC",
        "title": "Kane Train",
        "isrc": "GBCFB2000356",
        "url": "https://music.amazon.com/albums/B08DL2H5PV/?trackAsin=B08DL2BXQC"
      },
      "saveState": "SAVED"
    }
  }
}

Delete Track From Current User's Library

DELETE

/me/library/tracks/{id}

Authorization Scope: [music::library]

Remove a specified track from the current Amazon Music user’s library.

Path Parameters

Name	Data Type	Required	Description
id	string	Yes	The Amazon Music catalog ID of the track to remove.

curl --request DELETE '<base url>/v1/me/library/tracks/B097S29G3W' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>'

Response

Amazon Music response object containing:

Name	Data Type	Required	Description
removeTrack	SaveTrackResponse	No	Data about the removed Amazon Music track

Example

{
  "data": {
    "removeTrack": {
        "track": {
          "id": "B097S185X9",
          "title": "Something To Believe In",
          "isrc": "USATO2100125",
          "url": "https://music.amazon.com/albums/B097S29G3W/?trackAsin=B097S185X9"
        },
        "saveState": "REMOVED"
    }
  }
}

Get Current User's Liked Tracks

GET

/me/tracks

Authorization Scope: [music::favorites:read]

Retrieve songs that the current Amazon Music user has marked as ‘liked’. Optional parameters can be used to limit the number of songs returned.

Learn more about pagination.

Path Parameters

Name	Data Type	Required	Description
trackIds	string	No	A comma-separated list of track IDs. This method will check the user’s Like status against the specified tracks (if provided).
limit	number	No	The maximum number of tracks to return (default: 100). Minimum of 1, maximum of 100.
cursor	string	No	The cursor/token for the page to continue pagination results from.

Example

curl --request GET <base url>/v1/me/tracks
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>'

Response

Amazon Music response object containing:

Name	Data Type	Required	Description
user	User	No	Data about the current Amazon Music user, including their liked tracks

Example

{
  "data": {
    "user": {
      "id": "jj7vxoxnpmk6gx6qnywf4isb7y",
      "tracks": {
        "pageInfo": {
          "hasNextPage": false
        },
        "edgeCount": 1,
        "edges": [
          {
            "likeState": "DISLIKE",
            "node": {
              "id": "B01MXJA5O0",
              "title": "The Rattlin' Bog",
              "url": "https://music.amazon.com/albums/B01N9180QI/?trackAsin=B01MXJA5O0&do=play"
            }
          }
        ]
      }
    }
  }
}

Update Current User's Liked Tracks

PUT

/me/tracks/{trackId}

Authorization Scope: [music::favorites]

Save preference information for a track.

Path Parameters

Name	Data Type	Required	Description
trackId	string	Yes	The Amazon Music catalog ID of the track to save.

Request Body Parameters

Name	Data Type	Required	Description
likeState	string	Yes	Update the track depending on whether the user liked or disliked it. This is an enumerated type. The allowed values are LIKE and DISLIKE.

Example

curl --request PUT <base url>/v1/me/tracks/B000VRPGVA
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>'
--data  '{
  "likeState": "DISLIKE"
}'

Response

Amazon Music response object containing:

Name	Data Type	Required	Description
setTrackLikeState	Response	No	Data about the Amazon Music album

Example

{
  "data": {
    "setTrackLikeState": {
      "likeState": "DISLIKE",
      "track": {
        "id": "B000VRPGVA",
        "title": "Hold On Loosely",
        "url": "https://music.amazon.com/albums/B01N9180QI/?trackAsin=B01MXJA5O0"
      }
    }
  }
}