Amazon Music Web API

Web API Users 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.

Users

Get multiple users
Get user by ID
Get a user's playlists
Get a user's recently played tracks
Get a user's followers
Get a user's followed users
Get a user's followed artists
Get a user's followed podcast shows

Get multiple users

GET

/v2/users

Authorization Scope: [music::catalog]

Get public profile information for multiple AmazonMusic users identified by their IDs. Pass a comma-separated list of user IDs via the `ids` query parameter; maximum 100 IDs per request.

Query Parameters

Name	Data Type	Required	Description
ids	string[]	Yes	Comma-separated list of user IDs (max 100)

Response 200

Successful response

Response Schema

(array)

User[]

List of requested users

Example

[
  {
    "id": "B0DCXMPL01",
    "name": "John",
    "handle": "john123",
    "visibility": "PUBLIC",
    "url": "https://music.amazon.com/users/B0DCXMPL01",
    "images": [
      {
        "url": "https://m.media-amazon.com/images/I/user-profile-1.jpg",
        "width": 400,
        "height": 400
      }
    ]
  },
  {
    "id": "B0DCXMPL02",
    "name": "Jane",
    "handle": "jane456",
    "visibility": "PUBLIC",
    "url": "https://music.amazon.com/users/B0DCXMPL02",
    "images": [
      {
        "url": "https://m.media-amazon.com/images/I/user-profile-2.jpg",
        "width": 400,
        "height": 400
      }
    ]
  }
]

Error Responses

Response	Code	Status	Message
400	BAD_REQUEST	400	ids parameter is required and must contain 1-100 comma-separated IDs

400 Example

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

Get user by ID

GET

/v2/users/{id}

Authorization Scope: [music::catalog]

Retrieve a public AmazonMusic user's profile by id, including display name, handle, profile images, and visibility settings (`visibility`, `playbackVisibility`). Only publicly visible fields are returned; a private or non-existent profile yields a 404.

Path Parameters

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

Response 200

Successful response

Response Schema

_type

string

Discriminator value identifying this entity as a User

string

Unique user identifier

name

string

Display name of the user

handle

string

Public handle (username) chosen by the user

url

string [format=uri]

URL into AmazonMusic for this user profile

visibility

VisibilityType

Visibility setting that controls who can see this user's public profile.

playbackVisibility

VisibilityType

Visibility setting that controls who can see this user's playback activity.

countryCode

string

ISO 3166-1 alpha-2 country code of the music territory this user is currently authenticated against. Set by the service from the auth context for `me`-scoped responses; not present on third-party user lookups.

tier

enum (FREE|PRIME|UNLIMITED)

Subscription tier of the user.

images

Image[]

Avatar images for this user

Example

{
  "id": "B0DCXMPL01",
  "name": "John",
  "handle": "john123",
  "visibility": "PUBLIC",
  "playbackVisibility": "PUBLIC",
  "url": "https://music.amazon.com/users/B0DCXMPL01",
  "images": [
    {
      "url": "https://m.media-amazon.com/images/I/user-profile.jpg",
      "width": 400,
      "height": 400
    }
  ]
}

Error Responses

Response	Code	Status	Message
404	NOT_FOUND	404	User not found

404 Example

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

Get a user's playlists

GET

/v2/users/{id}/playlists

Authorization Scope: [music::catalog]

List the public playlists owned by an AmazonMusic user. Private playlists are never returned. Results are paginated with a forward-only cursor: set the page size with `first` (maximum 100) and pass the returned `nextToken` as the `after` cursor.

Path Parameters

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

Query Parameters

Name	Data Type	Required	Description
first	integer	No	Maximum number of playlists to return
after	string	No	Cursor for pagination

Response 200

Successful response

Response Schema

items

Playlist[]

Page of results.

nextToken

string

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

Example

{
  "items": [
    {
      "id": "B07GFQ5KZY",
      "title": "My Favorites",
      "trackCount": 42,
      "url": "https://music.amazon.com/playlists/B07GFQ5KZY",
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/playlist-cover.jpg",
          "width": 640,
          "height": 640
        }
      ]
    }
  ],
  "nextToken": "B0NEXTPG01"
}

Error Responses

Response	Code	Status	Message
404	NOT_FOUND	404	User not found

404 Example

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

Get a user's recently played tracks

GET

/v2/users/{id}/recently-played

Authorization Scope: [music::catalog]

List the entities a public AmazonMusic user has recently played, optionally filtered by `entityTypes` (a comma-separated list). Results are paginated with a forward-only cursor: set the page size with `first` (maximum 100) and pass the returned `nextToken` as the `after` cursor.

Path Parameters

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

Query Parameters

Name	Data Type	Required	Description
entityTypes	string[]	No	Comma-separated entity types to filter
first	integer	No	Maximum number of tracks to return
after	string	No	Cursor for pagination

Response 200

Successful response

Response Schema

items

Track[]

Page of results.

nextToken

string

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

Example

{
  "items": [
    {
      "id": "B000X6FP38",
      "title": "Goliath",
      "duration": 365
    }
  ],
  "nextToken": "B0NEXTPG01"
}

Error Responses

Response	Code	Status	Message
404	NOT_FOUND	404	User not found

404 Example

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

Get a user's followers

GET

/v2/users/{id}/followers

Authorization Scope: [music::catalog]

List the followers of a public AmazonMusic user. Results are paginated with a forward-only cursor: set the page size with `first` (maximum 100) and pass the returned `nextToken` as the `after` cursor to retrieve subsequent pages.

Path Parameters

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

Query Parameters

Name	Data Type	Required	Description
first	integer	No	Maximum number of users to return
after	string	No	Cursor for pagination

Response 200

Successful response

Response Schema

items

User[]

Page of results.

nextToken

string

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

Example

{
  "items": [
    {
      "id": "B0DCXMPL01",
      "name": "John",
      "handle": "john123",
      "url": "https://music.amazon.com/users/B0DCXMPL01",
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/user-profile.jpg",
          "width": 400,
          "height": 400
        }
      ]
    }
  ],
  "nextToken": "B0NEXTPG01"
}

Error Responses

Response	Code	Status	Message
404	NOT_FOUND	404	User not found

404 Example

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

Get a user's followed users

GET

/v2/users/{id}/followed/users

Authorization Scope: [music::catalog]

List the users that a public AmazonMusic user follows. Results are paginated with a forward-only cursor: set the page size with `first` (maximum 100) and pass the returned `nextToken` as the `after` cursor to fetch the next page.

Path Parameters

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

Query Parameters

Name	Data Type	Required	Description
first	integer	No	Maximum number of users to return
after	string	No	Cursor for pagination

Response 200

Successful response

Response Schema

items

User[]

Page of results.

nextToken

string

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

Example

{
  "items": [
    {
      "id": "B0DCXMPL01",
      "name": "John",
      "handle": "john123",
      "url": "https://music.amazon.com/users/B0DCXMPL01",
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/user-profile.jpg",
          "width": 400,
          "height": 400
        }
      ]
    }
  ],
  "nextToken": "B0NEXTPG01"
}

Error Responses

Response	Code	Status	Message
404	NOT_FOUND	404	User not found

404 Example

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

Get a user's followed artists

GET

/v2/users/{id}/followed/artists

Authorization Scope: [music::catalog]

List the artists that a public AmazonMusic user follows. Optionally pass `artistIds` (comma-separated) to restrict the results to specific artists. Results are paginated with a forward-only cursor: set the page size with `first` (maximum 100) and pass the returned `nextToken` as the `after` cursor to fetch the next page.

Path Parameters

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

Query Parameters

Name	Data Type	Required	Description
artistIds	string	No	Comma-separated artist IDs to limit the results to
first	integer	No	Maximum number of artists to return
after	string	No	Cursor for pagination

Response 200

Successful response

Response Schema

items

Artist[]

Page of results.

nextToken

string

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

Example

{
  "items": [
    {
      "id": "B000X6FP38",
      "name": "Karnivool",
      "followerCount": 123456,
      "url": "https://music.amazon.com/artists/B000X6FP38",
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/artist-primary.jpg",
          "width": 1200,
          "height": 1200,
          "imageType": "PRIMARY"
        }
      ]
    }
  ],
  "nextToken": "B0NEXTPG01"
}

Error Responses

Response	Code	Status	Message
404	NOT_FOUND	404	User not found

404 Example

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

Get a user's followed podcast shows

GET

/v2/users/{id}/followed/podcasts/shows

Authorization Scope: [music::catalog]

List the podcast shows that a public AmazonMusic user follows. Results are paginated with a forward-only cursor: set the page size with `first` (maximum 100) and pass the returned `nextToken` as the `after` cursor to page forward.

Path Parameters

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

Query Parameters

Name	Data Type	Required	Description
first	integer	No	Maximum number of podcast shows to return
after	string	No	Cursor for pagination

Response 200

Successful response

Response Schema

items

PodcastShow[]

Page of results.

nextToken

string

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

Example

{
  "items": [
    {
      "id": "B09WYF3XMZ",
      "title": "Tech Talks Daily",
      "url": "https://music.amazon.com/podcasts/B09WYF3XMZ",
      "images": [
        {
          "url": "https://m.media-amazon.com/images/I/podcast-cover.jpg",
          "width": 640,
          "height": 640
        }
      ]
    }
  ],
  "nextToken": "B0NEXTPG01"
}

Error Responses

Response	Code	Status	Message
404	NOT_FOUND	404	User not found

404 Example

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