Amazon Developer

Console

as

Settings
Sign out
Notifications
Alexa
Amazon Appstore
Ring
AWS
Documentation
Support
Contact Us
My Cases

Console

as

Amazon Music Web API

Web API Albums V2.0

Albums

Get multiple albums by IDs

GET
/v2/albums
Authorization Scope: [music::catalog]
Retrieve the Amazon Music catalog metadata for multiple albums in a single request. Available album fields include the title, release date, track count, duration, audio qualities, images, contributing artists, label, parental settings, and eligibility flags; use the sparse fieldset parameters below to select which to return.

Pass a comma-separated list of album IDs via the ids query parameter. Maximum 20 IDs per request. The response items are returned in the same order as the requested IDs; IDs that cannot be resolved produce a 404 for the whole request.

Supports sparse fieldsets via query parameters:

  • fields[album] — Comma-separated album fields (e.g. title,id,images,artists)
  • fields[artist] — Comma-separated artist fields (e.g. name)
  • fields[image] — Comma-separated image fields (e.g. url)
  • fields[track] — Comma-separated track fields (e.g. title,duration)

Query Parameters

Name Data Type Required Description
ids string[] Yes List of album IDs (max 20)
territory string No Territory code for content availability

Response 200

Successful response

Response Schema

(array)
Album[]

Example

Full response with every Album field populated

[
  {
    "id": "B073J5NW51",
    "title": "Sound Awake",
    "audioQualities": [
      "HD"
    ],
    "images": [
      {
        "height": 1400,
        "width": 1400,
        "url": "https://m.media-amazon.com/images/I/81uP7WboW6L.jpg",
        "imageType": "PRIMARY"
      },
      {
        "height": 500,
        "width": 500,
        "url": "https://m.media-amazon.com/images/I/51wbfl9b+CL.jpg",
        "imageType": "PRIMARY"
      }
    ],
    "artists": [
      {
        "id": "B000X6FP38",
        "name": "Karnivool"
      }
    ],
    "duration": 4329,
    "releaseDate": "2009-06-05T00:00:00.000Z",
    "trackCount": 11,
    "label": "Columbia",
    "url": "https://music.amazon.com.mx/albums/B073J5NW51?ref=dm_ff_amazonmusic_3p",
    "parentalSettings": {
      "hasExplicitLanguage": false
    }
  },
  {
    "id": "B07YVNQFHB",
    "title": "Asymmetry",
    "audioQualities": [
      "HD"
    ],
    "images": [
      {
        "height": 1400,
        "width": 1400,
        "url": "https://m.media-amazon.com/images/I/81vN5Iqg6XL.jpg",
        "imageType": "PRIMARY"
      }
    ],
    "artists": [
      {
        "id": "B000X6FP38",
        "name": "Karnivool"
      }
    ],
    "duration": 4821,
    "releaseDate": "2013-07-19T00:00:00.000Z",
    "trackCount": 10,
    "label": "Cymatic Records",
    "url": "https://music.amazon.com.mx/albums/B07YVNQFHB?ref=dm_ff_amazonmusic_3p",
    "parentalSettings": {
      "hasExplicitLanguage": false
    }
  }
]

Sparse Fieldsets Example

Sparse fieldsets — fields[album]=title,id,releaseDate,artists&fields[artist]=name

[
  {
    "id": "B073J5NW51",
    "title": "Sound Awake",
    "releaseDate": "2009-06-05T00:00:00.000Z",
    "artists": [
      {
        "id": "B000X6FP38",
        "name": "Karnivool"
      }
    ]
  },
  {
    "id": "B07YVNQFHB",
    "title": "Asymmetry",
    "releaseDate": "2013-07-19T00:00:00.000Z",
    "artists": [
      {
        "id": "B000X6FP38",
        "name": "Karnivool"
      }
    ]
  }
]

Error Responses

Response Code Status Message
400 BAD_REQUEST 400 ids parameter is required and must contain 1-20 comma-separated IDs
404 NOT_FOUND 404 One or more albums not found

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "ids parameter is required and must contain 1-20 comma-separated IDs",
    "traceId": "1-abc-def"
  }
}

404 Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "One or more albums not found",
    "traceId": "1-abc-def"
  }
}

Get top albums

GET
/v2/albums/top
Authorization Scope: [music::catalog]
Retrieve a list of the most popular albums in the Amazon Music catalog, ordered by popularity. Available album fields include the title, release date, track count, duration, audio qualities, images, contributing artists, label, parental settings, and eligibility flags; use the sparse fieldset parameters below to select which to return.

Paginated with forward-only cursor navigation. Default page size is 20 items; maximum is 100. Use the nextToken from the response to fetch the next page via the after query parameter.

Supports sparse fieldsets via query parameters:

  • fields[album] — Comma-separated album fields (e.g. title,id,images)
  • fields[artist] — Comma-separated artist fields (e.g. name)
  • fields[image] — Comma-separated image fields (e.g. url)

Query Parameters

Name Data Type Required Description
first integer No Number of items to return
after string No Cursor to start after

Response 200

Successful response

Response Schema

items
Album[]
Page of results.
nextToken
string
Cursor for the next page. Absent on the last page.

Example

Top albums with full Album fields populated

{
  "items": [
    {
      "id": "B084KP4NBH",
      "title": "The New Abnormal",
      "audioQualities": [
        "HD"
      ],
      "releaseDate": "2020-04-10T00:00:00.000Z",
      "label": "Cult",
      "url": "https://music.amazon.com/albums/B084KP4NBH",
      "artists": [
        {
          "id": "B00G70DLAS",
          "name": "the-strokes"
        }
      ],
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B084KP4NBH-640.jpg",
          "width": 640,
          "height": 640,
          "imageType": "PRIMARY"
        }
      ]
    }
  ],
  "nextToken": "B0EXAMP240"
}

Sparse Fieldsets Example

Sparse fieldsets — fields[album]=title,id,images&fields[image]=url

{
  "items": [
    {
      "id": "B084KP4NBH",
      "title": "The New Abnormal",
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B084KP4NBH-640.jpg"
        }
      ]
    }
  ],
  "nextToken": "B0EXAMP240"
}

Error Responses

Response Code Status Message
400 BAD_REQUEST 400 first parameter must be between 1 and 100

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "first parameter must be between 1 and 100",
    "traceId": "1-abc-def"
  }
}

Get album by ID

GET
/v2/albums/{id}
Authorization Scope: [music::catalog]
Retrieve the Amazon Music catalog metadata for a single album by its album id. Available album fields include the title, release date, track count, duration, audio qualities, images, contributing artists, the album's tracks, label, parental settings, and eligibility flags; use the sparse fieldset parameters below to select which to return.

Supports sparse fieldsets via query parameters:

  • fields[album] — Comma-separated album fields (e.g. title,id,images,artists,tracks)
  • fields[artist] — Comma-separated artist fields (e.g. name)
  • fields[image] — Comma-separated image fields (e.g. url)
  • fields[track] — Comma-separated track fields (e.g. title,duration)

Path Parameters

Name Data Type Required Description
id string Yes Unique identifier for the resource

Query Parameters

Name Data Type Required Description
territory string No Territory code for content availability

Response 200

Successful response

Response Schema

_type
string
Discriminator value identifying this entity as an Album
id
string
Unique album identifier
title
string
Album title
shortTitle
string
Short title of the album
audioQualities
array
Audio qualities available for this Album (SD is available by default)
audioQualities[]
enum (SD|HD|UHD|ATMOS|360RA)
globalAsin
string
Global unique identifier for the album
duration
number
Album duration in seconds
releaseDate
string
Date this album was released
label
string
Label associated with this album
trackCount
integer
Number of tracks in the album
url
string [format=uri]
URL into AmazonMusic for this album
images
Image[]
List of album images
availableMarkets
Market[]
List of available markets for this album
eligibility
Eligibility
parentalSettings
ParentalSettings
artists
BaseArtist[]
Artists contributing to this album
tracks
BaseTrack[]
Tracks in this album (paginated)

Example

Full album response

{
  "id": "B073J5NW51",
  "title": "Sound Awake",
  "audioQualities": [
    "HD"
  ],
  "images": [
    {
      "height": 1400,
      "width": 1400,
      "url": "https://m.media-amazon.com/images/I/81uP7WboW6L.jpg",
      "imageType": "PRIMARY"
    },
    {
      "height": 500,
      "width": 500,
      "url": "https://m.media-amazon.com/images/I/51wbfl9b+CL.jpg",
      "imageType": "PRIMARY"
    }
  ],
  "artists": [
    {
      "id": "B000X6FP38",
      "name": "Karnivool"
    }
  ],
  "duration": 4329,
  "releaseDate": "2009-06-05T00:00:00.000Z",
  "trackCount": 11,
  "label": "Columbia",
  "url": "https://music.amazon.com.mx/albums/B073J5NW51?ref=dm_ff_amazonmusic_3p",
  "parentalSettings": {
    "hasExplicitLanguage": false
  }
}

Sparse Fieldsets Example

Sparse fieldsets — fields[album]=title,id,artists&fields[artist]=name

{
  "id": "B073J5NW51",
  "title": "Sound Awake",
  "releaseDate": "2009-06-05T00:00:00.000Z",
  "artists": [
    {
      "id": "B000X6FP38",
      "name": "Karnivool"
    }
  ]
}

Error Responses

Response Code Status Message
400 BAD_REQUEST 400 Invalid field 'nonexistent' for type 'album'
404 NOT_FOUND 404 Album not found

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid field 'nonexistent' for type 'album'",
    "traceId": "1-abc-def"
  }
}

404 Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Album not found",
    "traceId": "1-abc-def"
  }
}

Get new album releases

GET
/v2/albums/new-releases
Authorization Scope: [music::catalog]
Retrieve newly released albums, sorted by release date descending. Available album fields include the title, release date, track count, duration, audio qualities, images, contributing artists, label, parental settings, and eligibility flags; use the sparse fieldset parameters below to select which to return.

Paginated with forward-only cursor navigation. Default page size is 20 items; maximum is 100. Use the nextToken from the response to fetch the next page via the after query parameter.

Supports sparse fieldsets via query parameters:

  • fields[album] — Comma-separated album fields (e.g. title,id,images,artists)
  • fields[artist] — Comma-separated artist fields (e.g. name)
  • fields[image] — Comma-separated image fields (e.g. url)

Query Parameters

Name Data Type Required Description
first integer No Number of items to return
after string No Cursor to start after

Response 200

Successful response

Response Schema

items
Album[]
Page of results.
nextToken
string
Cursor for the next page. Absent on the last page.

Example

First page of new-release albums with every field populated

{
  "items": [
    {
      "id": "B07YVNQFHB",
      "title": "Asymmetry",
      "audioQualities": [
        "HD"
      ],
      "images": [
        {
          "height": 1400,
          "width": 1400,
          "url": "https://m.media-amazon.com/images/I/81vN5Iqg6XL.jpg",
          "imageType": "PRIMARY"
        }
      ],
      "artists": [
        {
          "id": "B000X6FP38",
          "name": "Karnivool"
        }
      ],
      "duration": 4821,
      "releaseDate": "2013-07-19T00:00:00.000Z",
      "trackCount": 10,
      "label": "Cymatic Records",
      "url": "https://music.amazon.com.mx/albums/B07YVNQFHB?ref=dm_ff_amazonmusic_3p",
      "parentalSettings": {
        "hasExplicitLanguage": false
      }
    },
    {
      "id": "B073J5NW51",
      "title": "Sound Awake",
      "audioQualities": [
        "HD"
      ],
      "images": [
        {
          "height": 1400,
          "width": 1400,
          "url": "https://m.media-amazon.com/images/I/81uP7WboW6L.jpg",
          "imageType": "PRIMARY"
        }
      ],
      "artists": [
        {
          "id": "B000X6FP38",
          "name": "Karnivool"
        }
      ],
      "duration": 4329,
      "releaseDate": "2009-06-05T00:00:00.000Z",
      "trackCount": 11,
      "label": "Columbia",
      "url": "https://music.amazon.com.mx/albums/B073J5NW51?ref=dm_ff_amazonmusic_3p",
      "parentalSettings": {
        "hasExplicitLanguage": false
      }
    }
  ],
  "nextToken": "B0EXAMP201"
}

Sparse Fieldsets Example

Sparse fieldsets — fields[album]=title,id,releaseDate,artists&fields[artist]=name

{
  "items": [
    {
      "id": "B07YVNQFHB",
      "title": "Asymmetry",
      "releaseDate": "2013-07-19T00:00:00.000Z",
      "artists": [
        {
          "id": "B000X6FP38",
          "name": "Karnivool"
        }
      ]
    },
    {
      "id": "B073J5NW51",
      "title": "Sound Awake",
      "releaseDate": "2009-06-05T00:00:00.000Z",
      "artists": [
        {
          "id": "B000X6FP38",
          "name": "Karnivool"
        }
      ]
    }
  ],
  "nextToken": "B0EXAMP201"
}

Error Responses

Response Code Status Message
400 BAD_REQUEST 400 first parameter must be between 1 and 100

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "first parameter must be between 1 and 100",
    "traceId": "1-abc-def"
  }
}
Follow us:
amazon_developer_logo

© 2010-2026, Amazon.com, Inc. or its affiliates. All Rights Reserved.

Terms

Amazon Developer Blog

Contact Us