Amazon Music Web API

Web API Search V2.0

Important: These Amazon Music APIs are currently in a closed Beta. Please check back soon for updates.

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.

Search

Search all entity types
Search tracks
Search albums
Search artists
Search playlists
Search podcast shows
Search podcast episodes

Search all entity types

GET

/v2/search

Authorization Scope: [music::catalog]

Entity-agnostic search across the Amazon Music catalog. Returns a single `catalog` view whose entity groups carry the top hits plus per-type result buckets (albums, artists, tracks, stations, playlists, podcast shows, podcast episodes).

Each group exposes its own nextPageToken for paging deeper into that group; topHits is single-page. Use the limit query parameter to cap the number of items returned per group.

Each entity returns its base fields by default. Request richer metadata per entity type via sparse fieldsets:

fields[track] — e.g. artists,album
fields[album] — e.g. images,artists
fields[artist] — e.g. images
fields[playlist] — e.g. images
fields[station] — e.g. images
fields[podcastShow] — e.g. images
fields[podcastEpisode] — e.g. images,podcastShow

Query Parameters

Name	Data Type	Required	Description
query	string	Yes	The search text (1–300 characters)
limit	integer	No	Maximum number of items returned per entity group
territory	string	No	Territory code for content availability

Response 200

Successful response

Response Schema

string

Stable identifier for this view

entity

Entity

entityGroups

EntityGroup[]

Ordered list of entity groups composing the view

Example (default)

Default catalog view — entities carry base fields only

{
  "id": "catalog",
  "title": "Catalog Data",
  "content": {
    "entityGroups": [
      {
        "id": "topHits",
        "title": "Top Hits",
        "viewType": "LIST",
        "content": {
          "entities": [
            {
              "_type": "Artist",
              "id": "B00G9Y64K6",
              "name": "The Weeknd",
              "url": "https://music.amazon.com/artists/B00G9Y64K6"
            },
            {
              "_type": "Track",
              "id": "B086Q41M9C",
              "title": "Blinding Lights",
              "duration": 200,
              "isrc": "USUG11904206",
              "audioQualities": [
                "HD"
              ],
              "url": "https://music.amazon.com/albums/B084WLWSLG/?trackAsin=B086Q41M9C"
            }
          ]
        }
      },
      {
        "id": "albums",
        "title": "Albums",
        "viewType": "LIST",
        "content": {
          "entities": [
            {
              "_type": "Album",
              "id": "B084WLWSLG",
              "title": "After Hours",
              "releaseDate": "2020-03-20T00:00:00.000Z",
              "url": "https://music.amazon.com/albums/B084WLWSLG"
            }
          ],
          "nextPageToken": "tztok-v2_eyJvIjozfA"
        }
      }
    ]
  }
}

Sparse Fieldsets Example

Enriched — fields[album]=images,artists&fields[artist]=images

{
  "id": "catalog",
  "title": "Catalog Data",
  "content": {
    "entityGroups": [
      {
        "id": "albums",
        "title": "Albums",
        "viewType": "LIST",
        "content": {
          "entities": [
            {
              "_type": "Album",
              "id": "B084WLWSLG",
              "title": "After Hours",
              "releaseDate": "2020-03-20T00:00:00.000Z",
              "url": "https://music.amazon.com/albums/B084WLWSLG",
              "images": [
                {
                  "url": "https://m.media-amazon.com/images/I/B084WLWSLG-640.jpg",
                  "width": 640,
                  "height": 640,
                  "imageType": "PRIMARY"
                }
              ],
              "artists": [
                {
                  "id": "B00G9Y64K6",
                  "name": "The Weeknd"
                }
              ]
            }
          ],
          "nextPageToken": "tztok-v2_eyJvIjozfA"
        }
      }
    ]
  }
}

Error Responses

Response	Code	Status	Message
400	BAD_REQUEST	400	query parameter is required and must be 1-300 characters

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "query parameter is required and must be 1-300 characters",
    "traceId": "1-abc-def"
  }
}

Search tracks

POST

/v2/search/tracks

Authorization Scope: [music::catalog]

Search the Amazon Music catalog for tracks matching one or more search filters.

Filters are supplied in the request body. Each filter carries a free-text query and an optional field that narrows the match to a specific attribute (e.g. name, artistName, isrc). When field is omitted the query is treated as a free match. Multiple filters are combined to narrow the result set.

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[track] — Comma-separated track fields (e.g. title,id,duration,album,artists)
fields[album] — Comma-separated album fields (e.g. title,id)
fields[artist] — Comma-separated artist fields (e.g. name)

Query Parameters

Name	Data Type	Required	Description
first	integer	No	Number of items to return
after	string	No	Cursor to start after
territory	string	No	Territory code for content availability

Request Body

Request Schema

searchFilters

SearchTrackFilter[] [minItems=1]

Set of filters used to narrow the track search

sortBy

SortByType

Request Example

{
  "searchFilters": [
    {
      "field": "name",
      "query": "blinding lights"
    },
    {
      "field": "artistName",
      "query": "the weeknd"
    }
  ],
  "sortBy": "relevance"
}

Response 200

Successful response

Response Schema

items

Track[]

Page of results.

nextToken

string

Cursor for the next page. Absent on the last page.

Example

Track search results with full Track fields populated

{
  "items": [
    {
      "id": "B084WKYYC3",
      "title": "Blinding Lights",
      "duration": 200,
      "isrc": "USUG11904206",
      "audioQualities": [
        "HD"
      ],
      "mediaType": "audio",
      "releaseDate": "2020-03-20T00:00:00.000Z",
      "label": "XO",
      "url": "https://music.amazon.com/albums/B084WLWSLG/?trackAsin=B084WKYYC3",
      "album": {
        "id": "B084WLWSLG",
        "title": "After Hours"
      },
      "artists": [
        {
          "id": "B00G9Y64K6",
          "name": "The Weeknd"
        }
      ],
      "parentalSettings": {
        "hasExplicitLanguage": false
      }
    }
  ],
  "nextToken": "B0EXAMP240"
}

Sparse Fieldsets Example

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

{
  "items": [
    {
      "id": "B084WKYYC3",
      "title": "Blinding Lights",
      "duration": 200,
      "artists": [
        {
          "id": "B00G9Y64K6",
          "name": "The Weeknd"
        }
      ]
    }
  ],
  "nextToken": "B0EXAMP240"
}

Error Responses

Response	Code	Status	Message
400	BAD_REQUEST	400	searchFilters is required and must contain at least one filter

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "searchFilters is required and must contain at least one filter",
    "traceId": "1-abc-def"
  }
}

Search albums

POST

/v2/search/albums

Authorization Scope: [music::catalog]

Search the Amazon Music catalog for albums matching one or more search filters.

Filters are supplied in the request body. Each filter carries a free-text query and an optional field that narrows the match to a specific attribute (e.g. name, artistName). When field is omitted the query is treated as a free match. Multiple filters are combined to narrow the result set.

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,releaseDate)
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
territory	string	No	Territory code for content availability

Request Body

Request Schema

searchFilters

SearchAlbumFilter[] [minItems=1]

Set of filters used to narrow the album search

sortBy

SortByType

Request Example

{
  "searchFilters": [
    {
      "field": "name",
      "query": "after hours"
    },
    {
      "field": "artistName",
      "query": "the weeknd"
    }
  ],
  "sortBy": "relevance"
}

Response 200

Successful response

Response Schema

items

Album[]

Page of results.

nextToken

string

Cursor for the next page. Absent on the last page.

Example

Album search results with full Album fields populated

{
  "items": [
    {
      "id": "B084WLWSLG",
      "title": "After Hours",
      "releaseDate": "2020-03-20T00:00:00.000Z",
      "audioQualities": [
        "HD"
      ],
      "trackCount": 14,
      "duration": 3361,
      "label": "XO",
      "url": "https://music.amazon.com/albums/B084WLWSLG",
      "artists": [
        {
          "id": "B00G9Y64K6",
          "name": "The Weeknd"
        }
      ],
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B084WLWSLG-640.jpg",
          "width": 640,
          "height": 640,
          "imageType": "PRIMARY"
        }
      ],
      "parentalSettings": {
        "hasExplicitLanguage": true
      }
    }
  ],
  "nextToken": "B0EXAMP240"
}

Sparse Fieldsets Example

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

{
  "items": [
    {
      "id": "B084WLWSLG",
      "title": "After Hours",
      "releaseDate": "2020-03-20T00:00:00.000Z",
      "artists": [
        {
          "id": "B00G9Y64K6",
          "name": "The Weeknd"
        }
      ]
    }
  ],
  "nextToken": "B0EXAMP240"
}

Error Responses

Response	Code	Status	Message
400	BAD_REQUEST	400	searchFilters is required and must contain at least one filter

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "searchFilters is required and must contain at least one filter",
    "traceId": "1-abc-def"
  }
}

Search artists

POST

/v2/search/artists

Authorization Scope: [music::catalog]

Search the Amazon Music catalog for artists matching one or more search filters.

Filters are supplied in the request body. Each filter carries a free-text query and an optional field that narrows the match to a specific attribute (e.g. name). When field is omitted the query is treated as a free match. Multiple filters are combined to narrow the result set.

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[artist] — Comma-separated artist fields (e.g. name,id)
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
territory	string	No	Territory code for content availability

Request Body

Request Schema

searchFilters

SearchArtistFilter[] [minItems=1]

Set of filters used to narrow the artist search

sortBy

SortByType

Request Example

{
  "searchFilters": [
    {
      "field": "name",
      "query": "the weeknd"
    }
  ],
  "sortBy": "relevance"
}

Response 200

Successful response

Response Schema

items

Artist[]

Page of results.

nextToken

string

Cursor for the next page. Absent on the last page.

Example

Artist search results with full Artist fields populated

{
  "items": [
    {
      "id": "B00G9Y64K6",
      "name": "The Weeknd",
      "followerCount": 1200000,
      "url": "https://music.amazon.com/artists/B00G9Y64K6",
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B00G9Y64K6-640.jpg",
          "width": 640,
          "height": 640,
          "imageType": "PRIMARY"
        }
      ]
    }
  ],
  "nextToken": "B0EXAMP240"
}

Sparse Fieldsets Example

Sparse fieldsets — fields[artist]=name,id

{
  "items": [
    {
      "id": "B00G9Y64K6",
      "name": "The Weeknd"
    }
  ],
  "nextToken": "B0EXAMP240"
}

Error Responses

Response	Code	Status	Message
400	BAD_REQUEST	400	searchFilters is required and must contain at least one filter

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "searchFilters is required and must contain at least one filter",
    "traceId": "1-abc-def"
  }
}

Search playlists

POST

/v2/search/playlists

Authorization Scope: [music::catalog]

Search the Amazon Music catalog for playlists matching one or more search filters.

Filters are supplied in the request body. Each filter carries a free-text query and an optional field that narrows the match to a specific attribute (e.g. name, artistName). When field is omitted the query is treated as a free match. Multiple filters are combined to narrow the result set.

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[playlist] — Comma-separated playlist fields (e.g. title,id,trackCount)
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
territory	string	No	Territory code for content availability

Request Body

Request Schema

searchFilters

SearchPlaylistFilter[] [minItems=1]

Set of filters used to narrow the playlist search

sortBy

SortByType

Request Example

{
  "searchFilters": [
    {
      "field": "name",
      "query": "rock classics"
    }
  ],
  "sortBy": "relevance"
}

Response 200

Successful response

Response Schema

items

Playlist[]

Page of results.

nextToken

string

Cursor for the next page. Absent on the last page.

Example

Playlist search results with full Playlist fields populated

{
  "items": [
    {
      "id": "B07H51Z3B9",
      "title": "Rock Classics",
      "description": "Timeless rock anthems.",
      "visibility": "PUBLIC",
      "trackCount": 100,
      "duration": 24000,
      "url": "https://music.amazon.com/playlists/B07H51Z3B9",
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B07H51Z3B9-640.jpg",
          "width": 640,
          "height": 640,
          "imageType": "PRIMARY"
        }
      ]
    }
  ],
  "nextToken": "B0EXAMP240"
}

Sparse Fieldsets Example

Sparse fieldsets — fields[playlist]=title,id,trackCount

{
  "items": [
    {
      "id": "B07H51Z3B9",
      "title": "Rock Classics",
      "trackCount": 100
    }
  ],
  "nextToken": "B0EXAMP240"
}

Error Responses

Response	Code	Status	Message
400	BAD_REQUEST	400	searchFilters is required and must contain at least one filter

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "searchFilters is required and must contain at least one filter",
    "traceId": "1-abc-def"
  }
}

Search podcast shows

POST

/v2/search/podcasts/shows

Authorization Scope: [music::catalog]

Search the Amazon Music catalog for podcast shows matching one or more search filters.

Filters are supplied in the request body. Each filter carries a free-text query and an optional field that narrows the match to a specific attribute. When field is omitted the query is treated as a free match. Multiple filters are combined to narrow the result set.

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[podcastShow] — Comma-separated podcast show fields (e.g. title,id,author)
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
territory	string	No	Territory code for content availability

Request Body

Request Schema

searchFilters

SearchPodcastShowFilter[] [minItems=1]

Set of filters used to narrow the podcast show search

sortBy

SortByType

Request Example

{
  "searchFilters": [
    {
      "query": "true crime"
    }
  ],
  "sortBy": "relevance"
}

Response 200

Successful response

Response Schema

items

PodcastShow[]

Page of results.

nextToken

string

Cursor for the next page. Absent on the last page.

Example

Podcast show search results with full PodcastShow fields populated

{
  "items": [
    {
      "id": "B0EXAMP100",
      "title": "Cold",
      "type": "SERIAL",
      "description": "An investigative true-crime series.",
      "author": "KSL Podcasts",
      "url": "https://music.amazon.com/podcasts/B0EXAMP100",
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B0EXAMP100-640.jpg",
          "width": 640,
          "height": 640,
          "imageType": "PRIMARY"
        }
      ]
    }
  ],
  "nextToken": "B0EXAMP240"
}

Sparse Fieldsets Example

Sparse fieldsets — fields[podcastShow]=title,id,author

{
  "items": [
    {
      "id": "B0EXAMP100",
      "title": "Cold",
      "author": "KSL Podcasts"
    }
  ],
  "nextToken": "B0EXAMP240"
}

Error Responses

Response	Code	Status	Message
400	BAD_REQUEST	400	searchFilters is required and must contain at least one filter

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "searchFilters is required and must contain at least one filter",
    "traceId": "1-abc-def"
  }
}

Search podcast episodes

POST

/v2/search/podcasts/episodes

Authorization Scope: [music::catalog]

Search the Amazon Music catalog for podcast episodes matching one or more search filters.

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[podcastEpisode] — Comma-separated podcast episode fields (e.g. title,id,duration)
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
territory	string	No	Territory code for content availability

Request Body

Request Schema

searchFilters

SearchPodcastEpisodeFilter[] [minItems=1]

Set of filters used to narrow the podcast episode search

sortBy

SortByType

Request Example

{
  "searchFilters": [
    {
      "query": "cold case"
    }
  ],
  "sortBy": "relevance"
}

Response 200

Successful response

Response Schema

items

PodcastEpisode[]

Page of results.

nextToken

string

Cursor for the next page. Absent on the last page.

Example

Podcast episode search results with full PodcastEpisode fields populated

{
  "items": [
    {
      "id": "B0EXAMP110",
      "title": "Episode 1: The Case",
      "type": "FULL",
      "description": "The first episode of the series.",
      "author": "KSL Podcasts",
      "seasonNumber": 1,
      "episodeNumber": 1,
      "duration": 2400,
      "releaseDate": "2018-11-01T00:00:00.000Z",
      "url": "https://music.amazon.com/podcasts/B0EXAMP100/episodes/B0EXAMP110",
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/B0EXAMP110-640.jpg",
          "width": 640,
          "height": 640,
          "imageType": "PRIMARY"
        }
      ]
    }
  ],
  "nextToken": "B0EXAMP240"
}

Sparse Fieldsets Example

Sparse fieldsets — fields[podcastEpisode]=title,id,duration

{
  "items": [
    {
      "id": "B0EXAMP110",
      "title": "Episode 1: The Case",
      "duration": 2400
    }
  ],
  "nextToken": "B0EXAMP240"
}

Error Responses

Response	Code	Status	Message
400	BAD_REQUEST	400	searchFilters is required and must contain at least one filter

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "searchFilters is required and must contain at least one filter",
    "traceId": "1-abc-def"
  }
}