Amazon Music Web API

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

Playback

Get active playback queues
Create a new playback queue
Get the current playing entity
Get next entities in the queue
Insert item next in queue
Get previous entities in the queue
Get the queue view
Set loop mode on a queue
Set shuffle mode on a queue
Add item to end of queue
Get queue entities at position
Report a playback event
Report multiple playback events

Get active playback queues

GET

/v2/playback/queues/active

Authorization Scope: [music::playback]

Returns active playback queues for the current user. Includes queue state, current entity summary, and device state for each active queue.

Response 200

Active queues returned

Response Schema

data.queues

array

data.queues[].id

string

Queue ID

data.queues[].currentEntity._type

string

data.queues[].currentEntity.id

string

data.queues[].currentEntity.title

string

data.queues[].queueState

QueueState

Example

{
  "data": {
    "queues": [
      {
        "id": "aeddc6cc-149e-4614-905e-42cc7dd76ea5",
        "currentEntity": {
          "_type": "Track",
          "id": "B0GGHDD8X7",
          "title": "HELPMETAKEME"
        },
        "queueState": {
          "shuffleMode": "SHUFFLE_OFF",
          "loopMode": "LOOP_OFF",
          "playbackState": "PLAYING"
        }
      },
      {
        "id": "9d5c9917-4b01-4f01-a474-42b3229a91c4",
        "currentEntity": {
          "_type": "Track",
          "id": "B0GGGMQT5Y",
          "title": "IN_MY_HEAD"
        },
        "queueState": {
          "shuffleMode": "SHUFFLE_ON",
          "loopMode": "LOOP_ALL",
          "playbackState": "PLAYING"
        }
      }
    ]
  }
}

Error Responses

Response	Code	Status	Message
500	INTERNAL	500	An unexpected error occurred

500 Example

{
  "error": {
    "code": "INTERNAL",
    "message": "An unexpected error occurred",
    "traceId": "1-abc-def"
  }
}

Create a new playback queue

POST

/v2/playback/queues/new

Authorization Scope: [music::playback]

Creates a new playback queue for the specified content. Returns the initial queue entries with metadata needed to begin playback. Use `fields[playableEntity]`, `fields[entityControls]`, and `fields[queueControls]` query parameters to control which fields are included in the response.

Query Parameters

Name	Data Type	Required	Description
fields[playableEntity]	string (playbackInformation)	No	Request playback stream URL and DRM information for each entity. When omitted, entities are returned without streaming URLs.
fields[entityControls]	string	No	Comma-separated list of per-entity controls to include. Values: next, previous, scrubForward, scrubBackward, loopOne, like
fields[queueControls]	string	No	Comma-separated list of queue-level controls to include. Values: shuffle, loopAll, queueMutations, queueView, remainingSkips
limit	integer	No	Number of queue entities to return

Header Parameters

Name	Data Type	Required	Description
X-Amzn-Audio-DRMType	string (WIDEVINE\|FAIRPLAY)	No	DRM type for stream URL resolution
X-Amzn-Audio-Device-Capability	string	No	Comma-separated list of audio capabilities the device supports. Determines the audio quality of stream URLs returned in playbackInformation. Valid values: SD, HD, UHD, ATMOS, 360RA Example: SD,HD,UHD,ATMOS

Request Body

Request Schema

playParams

PlayParams

playbackOptions

PlaybackOptions

Request Example

{
  "playParams": {
    "id": "mrn:1.0:catalog:track:asin:B0GGGJJTWM"
  },
  "playbackOptions": {
    "shuffleMode": "SHUFFLE_OFF",
    "loopMode": "LOOP_OFF"
  }
}

Response 200

Playback queue created successfully

Response Schema

data

CreateQueueData

Sparse Fieldsets Example

Response with sparse fieldsets requesting playbackInformation, controls, and queueControls

{
  "data": {
    "id": "d60cebe4-5411-41ff-8026-dae74dbec7c9",
    "queueState": {
      "shuffleMode": "SHUFFLE_OFF",
      "loopMode": "LOOP_OFF",
      "playbackState": "STOPPED"
    },
    "queueControls": {
      "shuffle": {
        "isAllowed": true
      },
      "loopAll": {
        "isAllowed": true
      },
      "queueMutations": {
        "isAllowed": true
      },
      "queueView": {
        "isAllowed": true
      }
    },
    "pageInfo": {
      "hasNextPage": false
    },
    "entities": [
      {
        "entityReferenceId": "48d24228-9957-44b6-8f2a-7f076c12b56b",
        "metricId": "{\"entityId\":\"B0GGGJJTWM\",\"entityType\":\"TRACK\",\"playQueueId\":\"d60cebe4-5411-41ff-8026-dae74dbec7c9\"}",
        "entity": {
          "_type": "Track",
          "id": "B0GGGJJTWM",
          "duration": 91,
          "mediaType": "AUDIO",
          "url": "https://music.amazon.com.mx/tracks/B0GGGJJTWM",
          "playbackInformation": {
            "url": "https://d17vo8z6jop21h.cloudfront.net/api/DashDrm.mpd?dmid=200000712174198",
            "protocol": "DASH",
            "format": "ENCRYPTED_OPUS_FLAC",
            "expiredAt": "2026-06-24T02:14:19.667Z",
            "licenseUrl": null,
            "licenseHeaders": {
              "x-amz-music-rid": "23b6ca1b-051a-48b1-a46a-a73897c38f83",
              "x-amz-music-asin": "B0GGGJJTWM"
            },
            "applicationCertificate": null,
            "progressMilliseconds": null
          },
          "title": "The Abyss",
          "subtitle": "natori - The Abyss",
          "images": [
            {
              "url": "https://m.media-amazon.com/images/I/61X2HsAGIUL.jpg",
              "width": 1400,
              "height": 1400
            }
          ],
          "audioQualities": [
            "SD",
            "HD",
            "UHD"
          ],
          "isrc": "JPU902504551",
          "previewUrl": "https://music.amazon.com.mx/getSampleTrack/B0GGGJJTWM",
          "album": {
            "id": "B0GGH8LP4D",
            "title": "The Abyss"
          },
          "artists": [
            {
              "id": "B0BB1P1P8L",
              "name": "natori"
            }
          ]
        },
        "controls": {
          "next": {
            "isAllowed": true
          },
          "previous": {
            "isAllowed": true
          },
          "scrubForward": {
            "isAllowed": true
          },
          "scrubBackward": {
            "isAllowed": true
          },
          "loopOne": {
            "isAllowed": true
          },
          "like": {
            "isAllowed": true
          }
        }
      }
    ]
  }
}

Example (default)

Default response without sparse fieldsets (no controls or playbackInformation)

{
  "data": {
    "id": "d60cebe4-5411-41ff-8026-dae74dbec7c9",
    "queueState": {
      "shuffleMode": "SHUFFLE_OFF",
      "loopMode": "LOOP_OFF",
      "playbackState": "STOPPED"
    },
    "pageInfo": {
      "hasNextPage": false
    },
    "entities": [
      {
        "entityReferenceId": "48d24228-9957-44b6-8f2a-7f076c12b56b",
        "metricId": "{\"entityId\":\"B0GGGJJTWM\",\"entityType\":\"TRACK\",\"playQueueId\":\"d60cebe4-5411-41ff-8026-dae74dbec7c9\"}",
        "entity": {
          "_type": "Track",
          "id": "B0GGGJJTWM",
          "duration": 91,
          "mediaType": "AUDIO",
          "url": "https://music.amazon.com.mx/tracks/B0GGGJJTWM",
          "title": "The Abyss",
          "subtitle": "natori - The Abyss",
          "images": [
            {
              "url": "https://m.media-amazon.com/images/I/61X2HsAGIUL.jpg",
              "width": 1400,
              "height": 1400
            }
          ],
          "audioQualities": [
            "SD",
            "HD",
            "UHD"
          ],
          "isrc": "JPU902504551",
          "previewUrl": "https://music.amazon.com.mx/getSampleTrack/B0GGGJJTWM",
          "album": {
            "id": "B0GGH8LP4D",
            "title": "The Abyss"
          },
          "artists": [
            {
              "id": "B0BB1P1P8L",
              "name": "natori"
            }
          ]
        }
      }
    ]
  }
}

Error Responses

Response	Code	Status	Message
400	BAD_REQUEST	400	playParams is required
500	INTERNAL	500	An unexpected error occurred

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "playParams is required",
    "traceId": "1-abc-def"
  }
}

500 Example

{
  "error": {
    "code": "INTERNAL",
    "message": "An unexpected error occurred",
    "traceId": "1-abc-def"
  }
}

Get the current playing entity

GET

/v2/playback/queues/{id}/current

Authorization Scope: [music::playback]

Returns the currently playing entity in the queue. Use sparse fieldsets to control which fields are included in the response.

Path Parameters

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

Query Parameters

Name	Data Type	Required	Description
fields[playableEntity]	string (playbackInformation)	No	Request playback stream URL and DRM information for each entity. When omitted, entities are returned without streaming URLs.
fields[entityControls]	string	No	Comma-separated list of per-entity controls to include. Values: next, previous, scrubForward, scrubBackward, loopOne, like
fields[queueControls]	string	No	Comma-separated list of queue-level controls to include. Values: shuffle, loopAll, queueMutations, queueView, remainingSkips

Header Parameters

Name	Data Type	Required	Description
X-Amzn-Audio-DRMType	string (WIDEVINE\|FAIRPLAY)	No	DRM type for stream URL resolution
X-Amzn-Audio-Device-Capability	string	No	Comma-separated list of audio capabilities the device supports. Determines the audio quality of stream URLs returned in playbackInformation. Valid values: SD, HD, UHD, ATMOS, 360RA Example: SD,HD,UHD,ATMOS

Response 200

Current entity returned successfully

Response Schema

data.id

string

data.queueState

QueueState

data.queueControls

QueueControls

data.entity

QueueEntry

Example (withFieldsets)

Response with sparse fieldsets requesting playbackInformation, controls, and queueControls

{
  "data": {
    "id": "aeddc6cc-149e-4614-905e-42cc7dd76ea5",
    "queueState": {
      "shuffleMode": "SHUFFLE_OFF",
      "loopMode": "LOOP_OFF",
      "playbackState": "PLAYING"
    },
    "queueControls": {
      "shuffle": {
        "isAllowed": true
      },
      "loopAll": {
        "isAllowed": true
      },
      "queueMutations": {
        "isAllowed": true
      },
      "queueView": {
        "isAllowed": true
      }
    },
    "entity": {
      "entityReferenceId": "b6ab22c5-ac87-4011-b1ca-233f604d9c4e",
      "metricId": "{\"entityId\":\"B0GGGJJTWM\",\"entityType\":\"TRACK\",\"playQueueId\":\"aeddc6cc-149e-4614-905e-42cc7dd76ea5\"}",
      "entity": {
        "_type": "Track",
        "id": "B0GGGJJTWM",
        "duration": 91,
        "mediaType": "AUDIO",
        "url": "https://music.amazon.com.mx/tracks/B0GGGJJTWM",
        "playbackInformation": {
          "url": "https://d17vo8z6jop21h.cloudfront.net/api/DashDrm.mpd?dmid=200000712174198",
          "protocol": "DASH",
          "format": "ENCRYPTED_OPUS_FLAC",
          "expiredAt": "2026-06-24T02:21:11.842Z",
          "licenseUrl": null,
          "licenseHeaders": {
            "x-amz-music-rid": "842cf911-137d-49ee-aa59-28e1d6855f28",
            "x-amz-music-asin": "B0GGGJJTWM"
          },
          "applicationCertificate": null,
          "progressMilliseconds": null
        },
        "title": "The Abyss",
        "subtitle": "natori - The Abyss",
        "images": [
          {
            "url": "https://m.media-amazon.com/images/I/61X2HsAGIUL.jpg",
            "width": 1400,
            "height": 1400
          }
        ],
        "audioQualities": [
          "SD",
          "HD",
          "UHD"
        ],
        "isrc": "JPU902504551",
        "previewUrl": "https://music.amazon.com.mx/getSampleTrack/B0GGGJJTWM",
        "album": {
          "id": "B0GGH8LP4D",
          "title": "The Abyss"
        },
        "artists": [
          {
            "id": "B0BB1P1P8L",
            "name": "natori"
          }
        ]
      },
      "controls": {
        "next": {
          "isAllowed": true
        },
        "previous": {
          "isAllowed": true
        },
        "scrubForward": {
          "isAllowed": true
        },
        "scrubBackward": {
          "isAllowed": true
        },
        "loopOne": {
          "isAllowed": true
        },
        "like": {
          "isAllowed": true
        }
      }
    }
  }
}

Example (default)

Default response without sparse fieldsets (no controls or playbackInformation)

{
  "data": {
    "id": "aeddc6cc-149e-4614-905e-42cc7dd76ea5",
    "queueState": {
      "shuffleMode": "SHUFFLE_OFF",
      "loopMode": "LOOP_OFF",
      "playbackState": "PLAYING"
    },
    "entity": {
      "entityReferenceId": "b6ab22c5-ac87-4011-b1ca-233f604d9c4e",
      "metricId": "{\"entityId\":\"B0GGGJJTWM\",\"entityType\":\"TRACK\",\"playQueueId\":\"aeddc6cc-149e-4614-905e-42cc7dd76ea5\"}",
      "entity": {
        "_type": "Track",
        "id": "B0GGGJJTWM",
        "duration": 91,
        "mediaType": "AUDIO",
        "url": "https://music.amazon.com.mx/tracks/B0GGGJJTWM",
        "title": "The Abyss",
        "subtitle": "natori - The Abyss",
        "images": [
          {
            "url": "https://m.media-amazon.com/images/I/61X2HsAGIUL.jpg",
            "width": 1400,
            "height": 1400
          }
        ],
        "audioQualities": [
          "SD",
          "HD",
          "UHD"
        ],
        "isrc": "JPU902504551",
        "previewUrl": "https://music.amazon.com.mx/getSampleTrack/B0GGGJJTWM",
        "album": {
          "id": "B0GGH8LP4D",
          "title": "The Abyss"
        },
        "artists": [
          {
            "id": "B0BB1P1P8L",
            "name": "natori"
          }
        ]
      }
    }
  }
}

Response 206

Queue was restored before returning results. The queue ID and content may differ from the original queue. Requested sparse fieldsets are still honored in the response. Example shown without sparse fieldsets.

Response Schema

data.id

string

data.queueState

QueueState

data.queueControls

QueueControls

data.entity

QueueEntry

Example

{
  "data": {
    "id": "aeddc6cc-149e-4614-905e-42cc7dd76ea5",
    "queueState": {
      "shuffleMode": "SHUFFLE_OFF",
      "loopMode": "LOOP_OFF",
      "playbackState": "PLAYING"
    },
    "entity": {
      "entityReferenceId": "b6ab22c5-ac87-4011-b1ca-233f604d9c4e",
      "metricId": "{\"entityId\":\"B0GGGJJTWM\",\"entityType\":\"TRACK\",\"playQueueId\":\"aeddc6cc-149e-4614-905e-42cc7dd76ea5\"}",
      "entity": {
        "_type": "Track",
        "id": "B0GGGJJTWM",
        "duration": 91,
        "mediaType": "AUDIO",
        "url": "https://music.amazon.com.mx/tracks/B0GGGJJTWM",
        "title": "The Abyss",
        "subtitle": "natori - The Abyss",
        "images": [
          {
            "url": "https://m.media-amazon.com/images/I/61X2HsAGIUL.jpg",
            "width": 1400,
            "height": 1400
          }
        ],
        "audioQualities": [
          "SD",
          "HD",
          "UHD"
        ],
        "isrc": "JPU902504551",
        "previewUrl": "https://music.amazon.com.mx/getSampleTrack/B0GGGJJTWM",
        "album": {
          "id": "B0GGH8LP4D",
          "title": "The Abyss"
        },
        "artists": [
          {
            "id": "B0BB1P1P8L",
            "name": "natori"
          }
        ]
      }
    }
  }
}

Error Responses

Response	Code	Status	Message
404	NOT_FOUND	404	Queue not found
500	INTERNAL	500	An unexpected error occurred

404 Example

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

500 Example

{
  "error": {
    "code": "INTERNAL",
    "message": "An unexpected error occurred",
    "traceId": "1-abc-def"
  }
}

Get next entities in the queue

GET

/v2/playback/queues/{id}/next

Authorization Scope: [music::playback]

Returns the next entities after the current position. Use sparse fieldsets to control which fields are included in the response.

Path Parameters

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

Query Parameters

Name	Data Type	Required	Description
limit	integer	No	Number of entities to return
fields[playableEntity]	string (playbackInformation)	No	Request playback stream URL and DRM information for each entity. When omitted, entities are returned without streaming URLs.
fields[entityControls]	string	No	Comma-separated list of per-entity controls to include. Values: next, previous, scrubForward, scrubBackward, loopOne, like
fields[queueControls]	string	No	Comma-separated list of queue-level controls to include. Values: shuffle, loopAll, queueMutations, queueView, remainingSkips

Header Parameters

Name	Data Type	Required	Description
X-Amzn-Audio-DRMType	string (WIDEVINE\|FAIRPLAY)	No	DRM type for stream URL resolution
X-Amzn-Audio-Device-Capability	string	No	Comma-separated list of audio capabilities the device supports. Determines the audio quality of stream URLs returned in playbackInformation. Valid values: SD, HD, UHD, ATMOS, 360RA Example: SD,HD,UHD,ATMOS

Response 200

Next entities returned successfully

Response Schema

data.id

string

data.queueState

QueueState

data.queueControls

QueueControls

data.pageInfo

PageInfo

data.entities

QueueEntry[]

Example (withFieldsets)

Response with sparse fieldsets requesting playbackInformation, controls, and queueControls

{
  "data": {
    "id": "aeddc6cc-149e-4614-905e-42cc7dd76ea5",
    "queueState": {
      "shuffleMode": "SHUFFLE_OFF",
      "loopMode": "LOOP_OFF",
      "playbackState": "PLAYING"
    },
    "queueControls": {
      "shuffle": {
        "isAllowed": true
      },
      "loopAll": {
        "isAllowed": true
      },
      "queueMutations": {
        "isAllowed": true
      },
      "queueView": {
        "isAllowed": true
      }
    },
    "pageInfo": {
      "hasNextPage": true
    },
    "entities": [
      {
        "entityReferenceId": "90e591f5-643f-424c-b92e-d487a682fa71",
        "metricId": "{\"entityId\":\"B0GGHDD8X7\",\"entityType\":\"TRACK\",\"playQueueId\":\"aeddc6cc-149e-4614-905e-42cc7dd76ea5\"}",
        "entity": {
          "_type": "Track",
          "id": "B0GGHDD8X7",
          "duration": 165,
          "mediaType": "AUDIO",
          "url": "https://music.amazon.com.mx/tracks/B0GGHDD8X7",
          "playbackInformation": {
            "url": "https://d17vo8z6jop21h.cloudfront.net/api/DashDrm.mpd?dmid=200000712174198",
            "protocol": "DASH",
            "format": "ENCRYPTED_OPUS_FLAC",
            "expiredAt": "2026-06-24T02:21:11.842Z",
            "licenseUrl": null,
            "licenseHeaders": {
              "x-amz-music-rid": "842cf911-137d-49ee-aa59-28e1d6855f28",
              "x-amz-music-asin": "B0GGHDD8X7"
            },
            "applicationCertificate": null,
            "progressMilliseconds": null
          },
          "title": "HELPMETAKEME",
          "subtitle": "natori - The Abyss",
          "images": [
            {
              "url": "https://m.media-amazon.com/images/I/61X2HsAGIUL.jpg",
              "width": 1400,
              "height": 1400
            }
          ],
          "audioQualities": [
            "SD",
            "HD",
            "UHD"
          ],
          "isrc": "JPU902504552",
          "previewUrl": "https://music.amazon.com.mx/getSampleTrack/B0GGHDD8X7",
          "album": {
            "id": "B0GGH8LP4D",
            "title": "The Abyss"
          },
          "artists": [
            {
              "id": "B0BB1P1P8L",
              "name": "natori"
            }
          ]
        },
        "controls": {
          "next": {
            "isAllowed": true
          },
          "previous": {
            "isAllowed": true
          },
          "scrubForward": {
            "isAllowed": true
          },
          "scrubBackward": {
            "isAllowed": true
          },
          "loopOne": {
            "isAllowed": true
          },
          "like": {
            "isAllowed": true
          }
        }
      }
    ]
  }
}

Example (default)

Default response without sparse fieldsets (no controls or playbackInformation)

{
  "data": {
    "id": "aeddc6cc-149e-4614-905e-42cc7dd76ea5",
    "queueState": {
      "shuffleMode": "SHUFFLE_OFF",
      "loopMode": "LOOP_OFF",
      "playbackState": "PLAYING"
    },
    "pageInfo": {
      "hasNextPage": true
    },
    "entities": [
      {
        "entityReferenceId": "90e591f5-643f-424c-b92e-d487a682fa71",
        "metricId": "{\"entityId\":\"B0GGHDD8X7\",\"entityType\":\"TRACK\",\"playQueueId\":\"aeddc6cc-149e-4614-905e-42cc7dd76ea5\"}",
        "entity": {
          "_type": "Track",
          "id": "B0GGHDD8X7",
          "duration": 165,
          "mediaType": "AUDIO",
          "url": "https://music.amazon.com.mx/tracks/B0GGHDD8X7",
          "title": "HELPMETAKEME",
          "subtitle": "natori - The Abyss",
          "images": [
            {
              "url": "https://m.media-amazon.com/images/I/61X2HsAGIUL.jpg",
              "width": 1400,
              "height": 1400
            }
          ],
          "audioQualities": [
            "SD",
            "HD",
            "UHD"
          ],
          "isrc": "JPU902504552",
          "previewUrl": "https://music.amazon.com.mx/getSampleTrack/B0GGHDD8X7",
          "album": {
            "id": "B0GGH8LP4D",
            "title": "The Abyss"
          },
          "artists": [
            {
              "id": "B0BB1P1P8L",
              "name": "natori"
            }
          ]
        }
      }
    ]
  }
}

Response 206

Response Schema

data.id

string

data.queueState

QueueState

data.queueControls

QueueControls

data.pageInfo

PageInfo

data.entities

QueueEntry[]

Example

{
  "data": {
    "id": "aeddc6cc-149e-4614-905e-42cc7dd76ea5",
    "queueState": {
      "shuffleMode": "SHUFFLE_OFF",
      "loopMode": "LOOP_OFF",
      "playbackState": "PLAYING"
    },
    "pageInfo": {
      "hasNextPage": true
    },
    "entities": [
      {
        "entityReferenceId": "90e591f5-643f-424c-b92e-d487a682fa71",
        "metricId": "{\"entityId\":\"B0GGHDD8X7\",\"entityType\":\"TRACK\",\"playQueueId\":\"aeddc6cc-149e-4614-905e-42cc7dd76ea5\"}",
        "entity": {
          "_type": "Track",
          "id": "B0GGHDD8X7",
          "duration": 165,
          "mediaType": "AUDIO",
          "url": "https://music.amazon.com.mx/tracks/B0GGHDD8X7",
          "title": "HELPMETAKEME",
          "subtitle": "natori - The Abyss",
          "images": [
            {
              "url": "https://m.media-amazon.com/images/I/61X2HsAGIUL.jpg",
              "width": 1400,
              "height": 1400
            }
          ],
          "audioQualities": [
            "SD",
            "HD",
            "UHD"
          ],
          "isrc": "JPU902504552",
          "previewUrl": "https://music.amazon.com.mx/getSampleTrack/B0GGHDD8X7",
          "album": {
            "id": "B0GGH8LP4D",
            "title": "The Abyss"
          },
          "artists": [
            {
              "id": "B0BB1P1P8L",
              "name": "natori"
            }
          ]
        }
      }
    ]
  }
}

Error Responses

Response	Code	Status	Message
400	BAD_REQUEST	400	limit must be between 1 and 3
404	NO_MORE_NEXT_ENTITY	404	No more entities in the queue
500	INTERNAL	500	An unexpected error occurred

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "limit must be between 1 and 3",
    "traceId": "1-abc-def"
  }
}

404 Example

{
  "error": {
    "code": "NO_MORE_NEXT_ENTITY",
    "message": "No more entities in the queue",
    "traceId": "1-abc-def"
  }
}

500 Example

{
  "error": {
    "code": "INTERNAL",
    "message": "An unexpected error occurred",
    "traceId": "1-abc-def"
  }
}

Insert item next in queue

POST

/v2/playback/queues/{id}/next

Authorization Scope: [music::playback]

Inserts an item as the next item in the playback queue. The item will play immediately after the currently playing entity finishes. Returns a success status on completion.

Path Parameters

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

Request Body

Request Schema

playParams

PlayParams

entityReferenceId

string

Optional. The entity reference ID to insert after. If omitted, inserts after the currently playing entity.

Request Example

{
  "playParams": {
    "id": "mrn:1.0:catalog:track:asin:B084KPC3Q7"
  }
}

Response 200

Item inserted into queue

Response Schema

data.status

string

Example

{
  "data": {
    "status": "SUCCESS"
  }
}

Error Responses

Response	Code	Status	Message
403	FORBIDDEN	403	Queue mutations are not available for this queue
404	NOT_FOUND	404	Queue not found
500	INTERNAL	500	An unexpected error occurred

403 Example

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Queue mutations are not available for this queue",
    "traceId": "1-abc-def"
  }
}

404 Example

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

500 Example

{
  "error": {
    "code": "INTERNAL",
    "message": "An unexpected error occurred",
    "traceId": "1-abc-def"
  }
}

Get previous entities in the queue

GET

/v2/playback/queues/{id}/previous

Authorization Scope: [music::playback]

Returns the previous entities before the current position. Use sparse fieldsets to control which fields are included in the response.

Path Parameters

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

Query Parameters

Name	Data Type	Required	Description
limit	integer	No	Number of entities to return
fields[playableEntity]	string (playbackInformation)	No	Request playback stream URL and DRM information for each entity. When omitted, entities are returned without streaming URLs.
fields[entityControls]	string	No	Comma-separated list of per-entity controls to include. Values: next, previous, scrubForward, scrubBackward, loopOne, like
fields[queueControls]	string	No	Comma-separated list of queue-level controls to include. Values: shuffle, loopAll, queueMutations, queueView, remainingSkips

Header Parameters

Name	Data Type	Required	Description
X-Amzn-Audio-DRMType	string (WIDEVINE\|FAIRPLAY)	No	DRM type for stream URL resolution
X-Amzn-Audio-Device-Capability	string	No	Comma-separated list of audio capabilities the device supports. Determines the audio quality of stream URLs returned in playbackInformation. Valid values: SD, HD, UHD, ATMOS, 360RA Example: SD,HD,UHD,ATMOS

Response 200

Previous entities returned successfully

Response Schema

data.id

string

data.queueState

QueueState

data.queueControls

QueueControls

data.pageInfo

PageInfo

data.entities

QueueEntry[]

Example (withFieldsets)

Response with sparse fieldsets requesting playbackInformation, controls, and queueControls

{
  "data": {
    "id": "aeddc6cc-149e-4614-905e-42cc7dd76ea5",
    "queueState": {
      "shuffleMode": "SHUFFLE_OFF",
      "loopMode": "LOOP_OFF",
      "playbackState": "PLAYING"
    },
    "queueControls": {
      "shuffle": {
        "isAllowed": true
      },
      "loopAll": {
        "isAllowed": true
      },
      "queueMutations": {
        "isAllowed": true
      },
      "queueView": {
        "isAllowed": true
      }
    },
    "pageInfo": {
      "hasNextPage": true
    },
    "entities": [
      {
        "entityReferenceId": "90e591f5-643f-424c-b92e-d487a682fa71",
        "metricId": "{\"entityId\":\"B0GGHDD8X7\",\"entityType\":\"TRACK\",\"playQueueId\":\"aeddc6cc-149e-4614-905e-42cc7dd76ea5\"}",
        "entity": {
          "_type": "Track",
          "id": "B0GGHDD8X7",
          "duration": 165,
          "mediaType": "AUDIO",
          "url": "https://music.amazon.com.mx/tracks/B0GGHDD8X7",
          "playbackInformation": {
            "url": "https://d17vo8z6jop21h.cloudfront.net/api/DashDrm.mpd?dmid=200000712174198",
            "protocol": "DASH",
            "format": "ENCRYPTED_OPUS_FLAC",
            "expiredAt": "2026-06-24T02:21:11.842Z",
            "licenseUrl": null,
            "licenseHeaders": {
              "x-amz-music-rid": "842cf911-137d-49ee-aa59-28e1d6855f28",
              "x-amz-music-asin": "B0GGHDD8X7"
            },
            "applicationCertificate": null,
            "progressMilliseconds": null
          },
          "title": "HELPMETAKEME",
          "subtitle": "natori - The Abyss",
          "images": [
            {
              "url": "https://m.media-amazon.com/images/I/61X2HsAGIUL.jpg",
              "width": 1400,
              "height": 1400
            }
          ],
          "audioQualities": [
            "SD",
            "HD",
            "UHD"
          ],
          "isrc": "JPU902504552",
          "previewUrl": "https://music.amazon.com.mx/getSampleTrack/B0GGHDD8X7",
          "album": {
            "id": "B0GGH8LP4D",
            "title": "The Abyss"
          },
          "artists": [
            {
              "id": "B0BB1P1P8L",
              "name": "natori"
            }
          ]
        },
        "controls": {
          "next": {
            "isAllowed": true
          },
          "previous": {
            "isAllowed": true
          },
          "scrubForward": {
            "isAllowed": true
          },
          "scrubBackward": {
            "isAllowed": true
          },
          "loopOne": {
            "isAllowed": true
          },
          "like": {
            "isAllowed": true
          }
        }
      }
    ]
  }
}

Example (default)

Default response without sparse fieldsets (no controls or playbackInformation)

{
  "data": {
    "id": "aeddc6cc-149e-4614-905e-42cc7dd76ea5",
    "queueState": {
      "shuffleMode": "SHUFFLE_OFF",
      "loopMode": "LOOP_OFF",
      "playbackState": "PLAYING"
    },
    "pageInfo": {
      "hasNextPage": true
    },
    "entities": [
      {
        "entityReferenceId": "90e591f5-643f-424c-b92e-d487a682fa71",
        "metricId": "{\"entityId\":\"B0GGHDD8X7\",\"entityType\":\"TRACK\",\"playQueueId\":\"aeddc6cc-149e-4614-905e-42cc7dd76ea5\"}",
        "entity": {
          "_type": "Track",
          "id": "B0GGHDD8X7",
          "duration": 165,
          "mediaType": "AUDIO",
          "url": "https://music.amazon.com.mx/tracks/B0GGHDD8X7",
          "title": "HELPMETAKEME",
          "subtitle": "natori - The Abyss",
          "images": [
            {
              "url": "https://m.media-amazon.com/images/I/61X2HsAGIUL.jpg",
              "width": 1400,
              "height": 1400
            }
          ],
          "audioQualities": [
            "SD",
            "HD",
            "UHD"
          ],
          "isrc": "JPU902504552",
          "previewUrl": "https://music.amazon.com.mx/getSampleTrack/B0GGHDD8X7",
          "album": {
            "id": "B0GGH8LP4D",
            "title": "The Abyss"
          },
          "artists": [
            {
              "id": "B0BB1P1P8L",
              "name": "natori"
            }
          ]
        }
      }
    ]
  }
}

Response 206

Response Schema

data.id

string

data.queueState

QueueState

data.queueControls

QueueControls

data.pageInfo

PageInfo

data.entities

QueueEntry[]

Example

{
  "data": {
    "id": "aeddc6cc-149e-4614-905e-42cc7dd76ea5",
    "queueState": {
      "shuffleMode": "SHUFFLE_OFF",
      "loopMode": "LOOP_OFF",
      "playbackState": "PLAYING"
    },
    "pageInfo": {
      "hasNextPage": true
    },
    "entities": [
      {
        "entityReferenceId": "90e591f5-643f-424c-b92e-d487a682fa71",
        "metricId": "{\"entityId\":\"B0GGHDD8X7\",\"entityType\":\"TRACK\",\"playQueueId\":\"aeddc6cc-149e-4614-905e-42cc7dd76ea5\"}",
        "entity": {
          "_type": "Track",
          "id": "B0GGHDD8X7",
          "duration": 165,
          "mediaType": "AUDIO",
          "url": "https://music.amazon.com.mx/tracks/B0GGHDD8X7",
          "title": "HELPMETAKEME",
          "subtitle": "natori - The Abyss",
          "images": [
            {
              "url": "https://m.media-amazon.com/images/I/61X2HsAGIUL.jpg",
              "width": 1400,
              "height": 1400
            }
          ],
          "audioQualities": [
            "SD",
            "HD",
            "UHD"
          ],
          "isrc": "JPU902504552",
          "previewUrl": "https://music.amazon.com.mx/getSampleTrack/B0GGHDD8X7",
          "album": {
            "id": "B0GGH8LP4D",
            "title": "The Abyss"
          },
          "artists": [
            {
              "id": "B0BB1P1P8L",
              "name": "natori"
            }
          ]
        }
      }
    ]
  }
}

Error Responses

Response	Code	Status	Message
400	BAD_REQUEST	400	limit must be between 1 and 3
404	NO_MORE_PREVIOUS_ENTITY	404	No more previous entities in the queue
500	INTERNAL	500	An unexpected error occurred

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "limit must be between 1 and 3",
    "traceId": "1-abc-def"
  }
}

404 Example

{
  "error": {
    "code": "NO_MORE_PREVIOUS_ENTITY",
    "message": "No more previous entities in the queue",
    "traceId": "1-abc-def"
  }
}

500 Example

{
  "error": {
    "code": "INTERNAL",
    "message": "An unexpected error occurred",
    "traceId": "1-abc-def"
  }
}

Get the queue view

GET

/v2/playback/queues/{id}/view

Authorization Scope: [music::playback]

Returns upcoming entities in the queue for display purposes. Supports pagination via cursor. Results include entity metadata such as title, artist, and album information.

Path Parameters

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

Query Parameters

Name	Data Type	Required	Description
limit	integer	No
token	string	No	Pagination token from previous response

Response 200

Queue view returned

Response Schema

data.id

string

data.queueState

QueueState

data.pageInfo.hasNextPage

boolean

data.pageInfo.token

string

Pagination token for next page

data.entities

array

data.entities[].entityReferenceId

string

data.entities[].metricId

string

data.entities[].entity

PlayableEntityView

Example

{
  "data": {
    "id": "aeddc6cc-149e-4614-905e-42cc7dd76ea5",
    "queueState": {
      "shuffleMode": "SHUFFLE_OFF",
      "loopMode": "LOOP_OFF",
      "playbackState": "PLAYING"
    },
    "pageInfo": {
      "hasNextPage": true,
      "token": "b8de85d1-b4d1-4762-a281-9d87dcd59f8b"
    },
    "entities": [
      {
        "entityReferenceId": "90e591f5-643f-424c-b92e-d487a682fa71",
        "metricId": "{\"entityId\":\"B0GGHDD8X7\",\"entityType\":\"TRACK\",\"playQueueId\":\"aeddc6cc-149e-4614-905e-42cc7dd76ea5\"}",
        "entity": {
          "_type": "Track",
          "id": "B0GGHDD8X7",
          "duration": 165,
          "mediaType": "AUDIO",
          "url": "https://music.amazon.com.mx/tracks/B0GGHDD8X7",
          "title": "HELPMETAKEME",
          "subtitle": "natori - The Abyss",
          "images": [
            {
              "url": "https://m.media-amazon.com/images/I/61X2HsAGIUL.jpg",
              "width": 1400,
              "height": 1400
            }
          ],
          "audioQualities": [
            "SD",
            "HD",
            "UHD"
          ],
          "isrc": "JPU902504552",
          "previewUrl": "https://music.amazon.com.mx/getSampleTrack/B0GGHDD8X7",
          "album": {
            "id": "B0GGH8LP4D",
            "title": "The Abyss"
          },
          "artists": [
            {
              "id": "B0BB1P1P8L",
              "name": "natori"
            }
          ]
        }
      }
    ]
  }
}

Response 206

Response Schema

data.id

string

data.queueState

QueueState

data.pageInfo.hasNextPage

boolean

data.pageInfo.token

string

Pagination token for next page

data.entities

array

data.entities[].entityReferenceId

string

data.entities[].metricId

string

data.entities[].entity

PlayableEntityView

Example

{
  "data": {
    "id": "aeddc6cc-149e-4614-905e-42cc7dd76ea5",
    "queueState": {
      "shuffleMode": "SHUFFLE_OFF",
      "loopMode": "LOOP_OFF",
      "playbackState": "PLAYING"
    },
    "pageInfo": {
      "hasNextPage": true,
      "token": "b8de85d1-b4d1-4762-a281-9d87dcd59f8b"
    },
    "entities": [
      {
        "entityReferenceId": "90e591f5-643f-424c-b92e-d487a682fa71",
        "metricId": "{\"entityId\":\"B0GGHDD8X7\",\"entityType\":\"TRACK\",\"playQueueId\":\"aeddc6cc-149e-4614-905e-42cc7dd76ea5\"}",
        "entity": {
          "_type": "Track",
          "id": "B0GGHDD8X7",
          "duration": 165,
          "mediaType": "AUDIO",
          "url": "https://music.amazon.com.mx/tracks/B0GGHDD8X7",
          "title": "HELPMETAKEME",
          "subtitle": "natori - The Abyss",
          "images": [
            {
              "url": "https://m.media-amazon.com/images/I/61X2HsAGIUL.jpg",
              "width": 1400,
              "height": 1400
            }
          ],
          "audioQualities": [
            "SD",
            "HD",
            "UHD"
          ],
          "isrc": "JPU902504552",
          "previewUrl": "https://music.amazon.com.mx/getSampleTrack/B0GGHDD8X7",
          "album": {
            "id": "B0GGH8LP4D",
            "title": "The Abyss"
          },
          "artists": [
            {
              "id": "B0BB1P1P8L",
              "name": "natori"
            }
          ]
        }
      }
    ]
  }
}

Error Responses

Response	Code	Status	Message
400	BAD_REQUEST	400	limit must not exceed 10
404	NOT_FOUND	404	Queue not found
500	INTERNAL	500	An unexpected error occurred

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "limit must not exceed 10",
    "traceId": "1-abc-def"
  }
}

404 Example

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

500 Example

{
  "error": {
    "code": "INTERNAL",
    "message": "An unexpected error occurred",
    "traceId": "1-abc-def"
  }
}

Set loop mode on a queue

PUT

/v2/playback/queues/{id}/loop

Authorization Scope: [music::playback]

Sets the loop mode for the specified playback queue. Supports LOOP_ALL, LOOP_ONE, and LOOP_OFF modes. Returns a success status on completion.

Path Parameters

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

Request Body

Request Schema

loopMode

enum (LOOP_ALL|LOOP_ONE|LOOP_OFF)

Request Example

{
  "loopMode": "LOOP_ALL"
}

Response 200

Loop mode set

Response Schema

data.status

string

Example

{
  "data": {
    "status": "SUCCESS"
  }
}

Error Responses

Response	Code	Status	Message
403	FORBIDDEN	403	Loop is not available for this queue
404	NOT_FOUND	404	Queue not found
500	INTERNAL	500	An unexpected error occurred

403 Example

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Loop is not available for this queue",
    "traceId": "1-abc-def"
  }
}

404 Example

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

500 Example

{
  "error": {
    "code": "INTERNAL",
    "message": "An unexpected error occurred",
    "traceId": "1-abc-def"
  }
}

Set shuffle mode on a queue

PUT

/v2/playback/queues/{id}/shuffle

Authorization Scope: [music::playback]

Sets the shuffle mode for the specified playback queue. Supports SHUFFLE_ON and SHUFFLE_OFF modes. Returns a success status on completion.

Path Parameters

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

Request Body

Request Schema

shuffleMode

enum (SHUFFLE_ON|SHUFFLE_OFF)

Request Example

{
  "shuffleMode": "SHUFFLE_ON"
}

Response 200

Shuffle mode set

Response Schema

data.status

string

Example

{
  "data": {
    "status": "SUCCESS"
  }
}

Error Responses

Response	Code	Status	Message
403	FORBIDDEN	403	Shuffle is not available for this queue
404	NOT_FOUND	404	Queue not found
500	INTERNAL	500	An unexpected error occurred

403 Example

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Shuffle is not available for this queue",
    "traceId": "1-abc-def"
  }
}

404 Example

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

500 Example

{
  "error": {
    "code": "INTERNAL",
    "message": "An unexpected error occurred",
    "traceId": "1-abc-def"
  }
}

Add item to end of queue

POST

/v2/playback/queues/{id}/last

Authorization Scope: [music::playback]

Adds an item to the end of the playback queue. The item will play after all currently queued entities have finished. Returns a success status on completion.

Path Parameters

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

Request Body

Request Schema

playParams

PlayParams

Request Example

{
  "playParams": {
    "id": "mrn:1.0:catalog:track:asin:B084KW75Z6"
  }
}

Response 200

Item added to queue

Response Schema

data.status

string

Example

{
  "data": {
    "status": "SUCCESS"
  }
}

Error Responses

Response	Code	Status	Message
403	FORBIDDEN	403	Queue mutations are not available for this queue
404	NOT_FOUND	404	Queue not found
500	INTERNAL	500	An unexpected error occurred

403 Example

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Queue mutations are not available for this queue",
    "traceId": "1-abc-def"
  }
}

404 Example

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

500 Example

{
  "error": {
    "code": "INTERNAL",
    "message": "An unexpected error occurred",
    "traceId": "1-abc-def"
  }
}

Get queue entities at position

GET

/v2/playback/queues/{id}/entities/{entityReferenceId}

Authorization Scope: [music::playback]

Repositions the queue to the given entity reference and returns entities from that position. Automatically restores the queue if needed.

Path Parameters

Name	Data Type	Required	Description
id	string	Yes	Unique identifier for the resource
entityReferenceId	string	Yes	Entity reference ID to reposition to

Query Parameters

Name	Data Type	Required	Description
limit	integer	No
fields[playableEntity]	string (playbackInformation)	No	Request playback stream URL and DRM information for each entity. When omitted, entities are returned without streaming URLs.
fields[entityControls]	string	No	Comma-separated list of per-entity controls to include. Values: next, previous, scrubForward, scrubBackward, loopOne, like
fields[queueControls]	string	No	Comma-separated list of queue-level controls to include. Values: shuffle, loopAll, queueMutations, queueView, remainingSkips

Header Parameters

Name	Data Type	Required	Description
X-Amzn-Audio-DRMType	string (WIDEVINE\|FAIRPLAY)	No	DRM type for stream URL resolution
X-Amzn-Audio-Device-Capability	string	No	Comma-separated list of audio capabilities the device supports. Determines the audio quality of stream URLs returned in playbackInformation. Valid values: SD, HD, UHD, ATMOS, 360RA Example: SD,HD,UHD,ATMOS

Response 200

Queue entities returned

Response Schema

data.id

string

data.queueState

QueueState

data.queueControls

QueueControls

data.pageInfo

PageInfo

data.entities

QueueEntry[]

Example (withFieldsets)

Response with sparse fieldsets requesting playbackInformation, controls, and queueControls

{
  "data": {
    "id": "aeddc6cc-149e-4614-905e-42cc7dd76ea5",
    "queueState": {
      "shuffleMode": "SHUFFLE_OFF",
      "loopMode": "LOOP_OFF",
      "playbackState": "PLAYING"
    },
    "queueControls": {
      "shuffle": {
        "isAllowed": true
      },
      "loopAll": {
        "isAllowed": true
      },
      "queueMutations": {
        "isAllowed": true
      },
      "queueView": {
        "isAllowed": true
      }
    },
    "pageInfo": {
      "hasNextPage": true
    },
    "entities": [
      {
        "entityReferenceId": "90e591f5-643f-424c-b92e-d487a682fa71",
        "metricId": "{\"entityId\":\"B0GGHDD8X7\",\"entityType\":\"TRACK\",\"playQueueId\":\"aeddc6cc-149e-4614-905e-42cc7dd76ea5\"}",
        "entity": {
          "_type": "Track",
          "id": "B0GGHDD8X7",
          "duration": 165,
          "mediaType": "AUDIO",
          "url": "https://music.amazon.com.mx/tracks/B0GGHDD8X7",
          "playbackInformation": {
            "url": "https://d17vo8z6jop21h.cloudfront.net/api/DashDrm.mpd?dmid=200000712174198",
            "protocol": "DASH",
            "format": "ENCRYPTED_OPUS_FLAC",
            "expiredAt": "2026-06-24T02:21:11.842Z",
            "licenseUrl": null,
            "licenseHeaders": {
              "x-amz-music-rid": "842cf911-137d-49ee-aa59-28e1d6855f28",
              "x-amz-music-asin": "B0GGHDD8X7"
            },
            "applicationCertificate": null,
            "progressMilliseconds": null
          },
          "title": "HELPMETAKEME",
          "subtitle": "natori - The Abyss",
          "images": [
            {
              "url": "https://m.media-amazon.com/images/I/61X2HsAGIUL.jpg",
              "width": 1400,
              "height": 1400
            }
          ],
          "audioQualities": [
            "SD",
            "HD",
            "UHD"
          ],
          "isrc": "JPU902504552",
          "previewUrl": "https://music.amazon.com.mx/getSampleTrack/B0GGHDD8X7",
          "album": {
            "id": "B0GGH8LP4D",
            "title": "The Abyss"
          },
          "artists": [
            {
              "id": "B0BB1P1P8L",
              "name": "natori"
            }
          ]
        },
        "controls": {
          "next": {
            "isAllowed": true
          },
          "previous": {
            "isAllowed": true
          },
          "scrubForward": {
            "isAllowed": true
          },
          "scrubBackward": {
            "isAllowed": true
          },
          "loopOne": {
            "isAllowed": true
          },
          "like": {
            "isAllowed": true
          }
        }
      }
    ]
  }
}

Example (default)

Default response without sparse fieldsets (no controls or playbackInformation)

{
  "data": {
    "id": "aeddc6cc-149e-4614-905e-42cc7dd76ea5",
    "queueState": {
      "shuffleMode": "SHUFFLE_OFF",
      "loopMode": "LOOP_OFF",
      "playbackState": "PLAYING"
    },
    "pageInfo": {
      "hasNextPage": true
    },
    "entities": [
      {
        "entityReferenceId": "90e591f5-643f-424c-b92e-d487a682fa71",
        "metricId": "{\"entityId\":\"B0GGHDD8X7\",\"entityType\":\"TRACK\",\"playQueueId\":\"aeddc6cc-149e-4614-905e-42cc7dd76ea5\"}",
        "entity": {
          "_type": "Track",
          "id": "B0GGHDD8X7",
          "duration": 165,
          "mediaType": "AUDIO",
          "url": "https://music.amazon.com.mx/tracks/B0GGHDD8X7",
          "title": "HELPMETAKEME",
          "subtitle": "natori - The Abyss",
          "images": [
            {
              "url": "https://m.media-amazon.com/images/I/61X2HsAGIUL.jpg",
              "width": 1400,
              "height": 1400
            }
          ],
          "audioQualities": [
            "SD",
            "HD",
            "UHD"
          ],
          "isrc": "JPU902504552",
          "previewUrl": "https://music.amazon.com.mx/getSampleTrack/B0GGHDD8X7",
          "album": {
            "id": "B0GGH8LP4D",
            "title": "The Abyss"
          },
          "artists": [
            {
              "id": "B0BB1P1P8L",
              "name": "natori"
            }
          ]
        }
      }
    ]
  }
}

Response 206

Response Schema

data.id

string

data.queueState

QueueState

data.queueControls

QueueControls

data.pageInfo

PageInfo

data.entities

QueueEntry[]

Example

{
  "data": {
    "id": "aeddc6cc-149e-4614-905e-42cc7dd76ea5",
    "queueState": {
      "shuffleMode": "SHUFFLE_OFF",
      "loopMode": "LOOP_OFF",
      "playbackState": "PLAYING"
    },
    "pageInfo": {
      "hasNextPage": true
    },
    "entities": [
      {
        "entityReferenceId": "90e591f5-643f-424c-b92e-d487a682fa71",
        "metricId": "{\"entityId\":\"B0GGHDD8X7\",\"entityType\":\"TRACK\",\"playQueueId\":\"aeddc6cc-149e-4614-905e-42cc7dd76ea5\"}",
        "entity": {
          "_type": "Track",
          "id": "B0GGHDD8X7",
          "duration": 165,
          "mediaType": "AUDIO",
          "url": "https://music.amazon.com.mx/tracks/B0GGHDD8X7",
          "title": "HELPMETAKEME",
          "subtitle": "natori - The Abyss",
          "images": [
            {
              "url": "https://m.media-amazon.com/images/I/61X2HsAGIUL.jpg",
              "width": 1400,
              "height": 1400
            }
          ],
          "audioQualities": [
            "SD",
            "HD",
            "UHD"
          ],
          "isrc": "JPU902504552",
          "previewUrl": "https://music.amazon.com.mx/getSampleTrack/B0GGHDD8X7",
          "album": {
            "id": "B0GGH8LP4D",
            "title": "The Abyss"
          },
          "artists": [
            {
              "id": "B0BB1P1P8L",
              "name": "natori"
            }
          ]
        }
      }
    ]
  }
}

Error Responses

Response	Code	Status	Message
400	BAD_REQUEST	400	limit must be between 1 and 3
404	NOT_FOUND	404	Queue not found
500	INTERNAL	500	An unexpected error occurred

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "limit must be between 1 and 3",
    "traceId": "1-abc-def"
  }
}

404 Example

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

500 Example

{
  "error": {
    "code": "INTERNAL",
    "message": "An unexpected error occurred",
    "traceId": "1-abc-def"
  }
}

Report a playback event

POST

/v2/playback/events

Authorization Scope: [music::playback]

Report a single playback event to the Amazon Music service. The client must report start and stop events for each track to ensure correct queue progression and streaming attribution.

Header Parameters

Name	Data Type	Required	Description
X-Amzn-Device-Id	string	No	Device identifier used for streaming metrics and playback attribution

Request Body

Request Schema

metricId

string

Opaque metric context JSON string returned in queue entity responses. Must be passed back unchanged when reporting playback events. Contains entity identification, queue context, and selection source metadata.

event.playbackState

enum (PLAYING|STOPPED)

Current playback state. PLAYING: Playback has started or resumed. STOPPED: Playback has ended (user action or track finished).

event.clientTimestampInMilliseconds

integer [format=int64]

Client-side Unix timestamp in milliseconds when the event occurred.

event.playbackStartAbsoluteOffsetMilliseconds

integer

Required for PLAYING events. Absolute offset in milliseconds from where playback starts within a track (0 for beginning, or scrub position).

event.entityProgressSeconds

number

Required for STOPPED events. The current absolute playback position within this track in seconds.

event.terminationReason

Required for STOPPED events. Reason playback ended.

event.durationSeconds

number

Required for STOPPED events. Duration in seconds of playback since the start of the track or since the last interruption.

event.rebufferCount

integer

Required for STOPPED events. Number of times playback was interrupted by rebuffering since the last start event.

event.initialPlaybackDelayMilliseconds

integer

Time in milliseconds between when playback was requested and when audio actually started or stopped.

event.deviceTimezone

string

Device timezone offset (e.g. "-06:00").

event.playbackCurrentSpeed

number

Current playback speed factor (e.g. 1.0 for normal speed).

options.takeOverType

enum (FORCE|AUTO)

Device takeover strategy for concurrent streams. AUTO: Attempt normal report, fall back to takeover on concurrent limit. FORCE: Immediately take over the stream from other devices.

Request Example

{
  "metricId": "{\"entityId\":\"B0GGHDD8X7\",\"playbackInstanceId\":\"90e591f5-643f-424c-b92e-d487a682fa71\",\"metricsSpec\":\"TRACK\",\"resourceType\":\"UNLIMITED_MUSIC\",\"playQueueId\":\"aeddc6cc-149e-4614-905e-42cc7dd76ea5\",\"selectionSourceType\":\"ALBUM\",\"selectionSourceId\":\"B0GGH8LP4D\",\"entityIdType\":\"ASIN\",\"entityType\":\"TRACK\"}",
  "event": {
    "playbackState": "PLAYING",
    "playbackStartAbsoluteOffsetMilliseconds": 0,
    "clientTimestampInMilliseconds": 1718568000000,
    "initialPlaybackDelayMilliseconds": 150,
    "deviceTimezone": "-06:00",
    "playbackCurrentSpeed": 1
  },
  "options": {
    "takeOverType": "AUTO"
  }
}

Response 200

Playback event reported successfully

Response Schema

data.status

string

Example

{
  "data": {
    "status": "SUCCESS"
  }
}

Error Responses

Response	Code	Status	Message
400	BAD_REQUEST	400	Invalid metricId format
429	MAX_CONCURRENCY_REACHED	429	Concurrent stream limit exceeded
500	INTERNAL	500	An unexpected error occurred

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid metricId format",
    "traceId": "1-abc-def"
  }
}

429 Example

{
  "error": {
    "code": "MAX_CONCURRENCY_REACHED",
    "message": "Concurrent stream limit exceeded",
    "traceId": "1-abc-def"
  }
}

500 Example

{
  "error": {
    "code": "INTERNAL",
    "message": "An unexpected error occurred",
    "traceId": "1-abc-def"
  }
}

Report multiple playback events

POST

/v2/playback/events/batch

Authorization Scope: [music::playback]

Reports multiple playback events in a single request. Use this endpoint to batch state transitions that occurred while offline or in quick succession, reducing the number of individual network calls needed.

Header Parameters

Name	Data Type	Required	Description
X-Amzn-Device-Id	string	No	Device identifier used for streaming metrics and playback attribution

Request Body

Request Schema

events

array

events[].metricId

string

Metric context string returned by queue endpoints. Must be passed back unchanged.

events[].event.playbackState

enum (PLAYING|STOPPED)

events[].event.clientTimestampInMilliseconds

integer [format=int64]

events[].event.playbackStartAbsoluteOffsetMilliseconds

integer

Required for PLAYING events. Offset in ms where playback starts.

events[].event.entityProgressSeconds

number

Required for STOPPED events. Absolute playback position in seconds.

events[].event.terminationReason

events[].event.durationSeconds

number

events[].event.rebufferCount

integer

events[].event.initialPlaybackDelayMilliseconds

integer

events[].event.deviceTimezone

string

events[].event.playbackCurrentSpeed

number

options.takeOverType

enum (FORCE|AUTO)

Request Example

{
  "events": [
    {
      "metricId": "{\"entityId\":\"B0GGHDD8X7\",\"playbackInstanceId\":\"90e591f5-643f-424c-b92e-d487a682fa71\",\"entityType\":\"TRACK\",\"playQueueId\":\"aeddc6cc-149e-4614-905e-42cc7dd76ea5\"}",
      "event": {
        "playbackState": "STOPPED",
        "entityProgressSeconds": 241,
        "clientTimestampInMilliseconds": 1718568241000,
        "initialPlaybackDelayMilliseconds": 0,
        "deviceTimezone": "-06:00",
        "playbackCurrentSpeed": 1,
        "durationSeconds": 241,
        "rebufferCount": 0,
        "terminationReason": "trackFinished"
      }
    }
  ],
  "options": {
    "takeOverType": "AUTO"
  }
}

Response 200

Events reported successfully

Response Schema

data.status

string

Example

{
  "data": {
    "status": "SUCCESS"
  }
}

Error Responses

Response	Code	Status	Message
400	BAD_REQUEST	400	events array is required
429	MAX_CONCURRENCY_REACHED	429	Concurrent stream limit exceeded
500	INTERNAL	500	An unexpected error occurred

400 Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "events array is required",
    "traceId": "1-abc-def"
  }
}

429 Example

{
  "error": {
    "code": "MAX_CONCURRENCY_REACHED",
    "message": "Concurrent stream limit exceeded",
    "traceId": "1-abc-def"
  }
}

500 Example

{
  "error": {
    "code": "INTERNAL",
    "message": "An unexpected error occurred",
    "traceId": "1-abc-def"
  }
}