Amazon Music Web API

Playback V1.0

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

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

Web Playback

API endpoints for retrieving and updating track objects for playback. For an explanation of the basics of playback, see the playback overview.

Create New Session
Get Current Track
Get Next Tracks
Get Previous Tracks
Get Playback Queue
Get Active Sessions
Restore Playback Session
Queue Next Track
Queue Last Track
Set Playback Mode to Loop
Set Playback Mode to Shuffle
Report Single Event
Report Multiple Events

Create New Session

POST

/v1/playback/sessions

Authorization Scope: [music::playback]

Initialize a new session and playback queue. Either playParams.id or playParams.containerIds must be provided.

Request Parameters

Name	Data Type	Required	Description
playParams.id	string	Yes	The ID (MRN format) of the item for playback.
playParams.containerIds	string[]	No	An array of strings of IDs (MRN format) defining the container context of the current playback item. It can be a list of tracks or a single container such as a playlist or album.
playbackOptions.shuffleMode	string	No	Enable or disable shuffle mode for playback. Allowed values are 'SHUFFLE_ON' and 'SHUFFLE_OFF'.
playbackOptions.loopMode	string	No	Enable or disable shuffle mode for playback. Allowed values are 'LOOP_ON' and 'LOOP_OFF'.
playbackOptions.startAsStation	bool	No	Start a station based on the requested track. If this parameter is set, shuffleMode will be ignored.
playbackOptions.playbackContinuationMode	string	No	An optional parameter specifying whether to continue populating the playback queue at the end of the specified context or not. Supported values are 'AUTOPLAY_ON' and 'AUTOPLAY_OFF'.
limit	number	No	This sets the size of the playback queue window returned to the client. Must be a number between 1 and 11 inclusive.

Example

curl --request POST '<base url>/v1/playback/sessions' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--header 'X-Amzn-Audio-DRMType: WIDEVINE' \
--header 'X-Amzn-Audio-Device-Capability: STD_RES,HI_FI,HI_RES,THREE_DIMENSIONAL' \
--header 'X-Amzn-Device-Id: <your unique device ID>' \
--header 'Content-Type: application/json' \
--data '{
    "playParams": {
        "id": "mrn:1.0:catalog:track:asin:B084KVZP2G",
        "containerIds": [
            "mrn:1.0:catalog:album:asin:B084KYMDXT"
        ]
    },
    "playbackOptions": {
        "playbackContinuationMode": "AUTOPLAY_ON",
        "shuffleMode": "SHUFFLE_OFF",
        "loopMode": "LOOP_OFF",
        "startAsStation": false
    },
    "limit": 5
}'

Response

Amazon Music response object containing:

Name	Data Type	Required	Description
data	InitialPlaybackSessionResponse	Yes	Playback session object including a limited window of the new playback queue.

The response body will provide a limited window of the playback queue that has been created on the Amazon Music server for this playback session. It contains up to 11 upcoming tracks in the queue.

Once the client has started playback of the first track and sent the corresponding playback event to /v1/playback/event, this track will become the current track of the queue.

Example response for an Unlimited subscriber

(Some lines omitted for brevity)

{
    "data": {
        "pageInfo": {
            "hasNextPage": true
        },
        "entities": [
            {
                "sessionId": "1abc0c30-70b1-42ea-9f0f-20049d2b9aa3",
                "entityReferenceId": "56dc5334-c30a-4bfd-a8e8-9b92bfedefc2",
                "metricId": "{\"entityId\":\"B084KW75Z6\",\"playbackInstanceId\":\"56dc5334-c30a-4bfd-a8e8-9b92bfedefc2\",\"metricsSpec\":\"TRACK\",\"playQueueId\":\"1abc0c30-70b1-42ea-9f0f-20049d2b9aa3\",\"resourceType\":\"UNLIMITED_MUSIC\",\"selectionSourceId\":\"B084KYMDXT\",\"trackCount\":\"1\",\"selectionSourceType\":\"ALBUM\",\"selectionSourceSessionId\":\"1abc0c30-70b1-42ea-9f0f-20049d2b9aa3\",\"entityIdType\":\"ASIN\",\"entityType\":\"TRACK\",\"isExplicitLanguageFilterOn\":\"true\",\"enqueueState\":\"audio\",\"streamOrDRMTech\":\"DASH\"}",
                "actions": {
                    "next": {
                        "isAllowed": true
                    },
                    "previous": {
                        "isAllowed": true
                    },
                    "scrubForward": {
                        "isAllowed": true
                    },
                    "scrubBackward": {
                        "isAllowed": true
                    },
                    "loopOne": {
                        "isAllowed": true
                    },
                    "rate": {
                        "isAllowed": false
                    },
                    "queueMutations": {
                        "isAllowed": true
                    },
                    "queueView": {
                        "isAllowed": true
                    },
                    "loopAll": {
                        "isAllowed": true
                    },
                    "shuffle": {
                        "isAllowed": true
                    }
                },
                "track": {
                    "id": "B084KW75Z6",
                    "_type": "Track",
                    "mediaType": "AUDIO",
                    "url": "https://music.amazon.com/albums/B084KP4NBH/?trackAsin=B084KW75Z6&do=play&ref=dm_ff_amazonmusic.3p",
                    "playbackInformation": {
                        "url": "https://d17vo8z6jop21h.cloudfront.net/api/DashDrm.mpd?dmid=200000347977163&ld=true&sd=true&hd=true&uhd=true&3d=true&ra360=false&ac4=false&mhm1=false&v=opus_flac_e&drm=wv&r=026c7644-785d-44c9-ba37-8a54606b323c&rgn=NA&dtype=A3PMWP4IZPXWSV",
                        "protocol": "DASH",
                        "format": "ENCRYPTED_OPUS_FLAC",
                        "licenseHeaders":...,
                        "applicationCertificate": null,
                        "progressMilliseconds": null
                    },
                    "title": "The Adults Are Talking [Explicit]",
                    "subtitle": "The Strokes - The New Abnormal [Explicit]",
                    "isrc": "USRC11902726",
                    "images": ...,
                    "duration": 309,
                    "album": {
                        "id": "B084KP4NBH",
                        "title": "The New Abnormal [Explicit]"
                    },
                    "artists": [
                        {
                            "id": "B00G70DLAS",
                            "name": "The Strokes"
                        }
                    ]
                }
            },
            {
                "sessionId": "1abc0c30-70b1-42ea-9f0f-20049d2b9aa3",
                "entityReferenceId": "d9e552aa-1acb-42e3-b0a7-fbab15a2abf1",
                "metricId": "{\"entityId\":\"B084KPC3Q7\",\"playbackInstanceId\":\"d9e552aa-1acb-42e3-b0a7-fbab15a2abf1\",\"metricsSpec\":\"TRACK\",\"playQueueId\":\"1abc0c30-70b1-42ea-9f0f-20049d2b9aa3\",\"resourceType\":\"UNLIMITED_MUSIC\",\"selectionSourceId\":\"B084KYMDXT\",\"trackCount\":\"1\",\"selectionSourceType\":\"ALBUM\",\"selectionSourceSessionId\":\"1abc0c30-70b1-42ea-9f0f-20049d2b9aa3\",\"entityIdType\":\"ASIN\",\"entityType\":\"TRACK\",\"isExplicitLanguageFilterOn\":\"true\",\"enqueueState\":\"audio\",\"streamOrDRMTech\":\"DASH\"}",
                "actions": ...
                },
                "track": ...
            },
            {
                "sessionId": "1abc0c30-70b1-42ea-9f0f-20049d2b9aa3",
                "entityReferenceId": "074a07d0-e5f1-428a-801f-b3bbe67d0950",
                "metricId": "{\"entityId\":\"B084KMZM11\",\"playbackInstanceId\":\"074a07d0-e5f1-428a-801f-b3bbe67d0950\",\"metricsSpec\":\"TRACK\",\"playQueueId\":\"1abc0c30-70b1-42ea-9f0f-20049d2b9aa3\",\"resourceType\":\"UNLIMITED_MUSIC\",\"selectionSourceId\":\"B084KYMDXT\",\"trackCount\":\"1\",\"selectionSourceType\":\"ALBUM\",\"selectionSourceSessionId\":\"1abc0c30-70b1-42ea-9f0f-20049d2b9aa3\",\"entityIdType\":\"ASIN\",\"entityType\":\"TRACK\",\"isExplicitLanguageFilterOn\":\"true\",\"enqueueState\":\"audio\",\"streamOrDRMTech\":\"DASH\"}",
                "actions": ...,
                "track": ...
            }
        ],
        "metadata": {
            "loopMode": "LOOP_OFF",
            "shuffleMode": "SHUFFLE_OFF",
            "playbackState": "STOPPED"
        }
    }
}

The reponse contains metadata for the created playback queue (the current and upcoming tracks), including PlaybackMetadata (current loop and shuffle mode) and allowed customer Actions.

The Actions object attached to each playqueue entity contains valuable information that the client will need for rendering playback transport controls and a view of the queue. It specifies which transport controls (scrubbing, skipping, switching playback rate) can or must not be enabled, and if applicable, a reason for it. Depending on the subscription tier, certain controls might be deactivated because the customer has exceeded their allowed skip limit. For some cases, mostly station playback, the client might not allowed to show the queue of upcoming tracks (queueView).

In the example response above, almost all customer actions are allowed, meaning that the client should enable the corresponding transport controls (e.g. next, previous). The client is not supposed to modify the playback rate, which is typically the case for Music, as opposed to Podcast content.

Example response for a Prime subscriber

(Some lines omitted for brevity)

{
    "data": {
        "pageInfo": {
            "hasNextPage": true
        },
        "entities": [
            {
                "sessionId": "31c0cf5c-b7a0-49eb-b1f6-40ec1f2dfcb3",
                "entityReferenceId": "03f4704e-a7bd-4128-80d5-5d8d68d719dd",
                "metricId": "{\"entityId\":\"B084KPC3Q7\",\"playbackInstanceId\":\"03f4704e-a7bd-4128-80d5-5d8d68d719dd\",\"metricsSpec\":\"TRACK\",\"selectionSourceSubType\":\"47d3c49c-1aed-4d40-9822-ea121fd64789\",\"fulfillmentSourceType\":\"AUGMENTED_SHUFFLE\",\"isCustomerSelectedEntity\":\"false\",\"selectionSourceId\":\"B084KYMDXT\",\"isAugmentedTrack\":\"false\",\"isOnDemandQueue\":\"false\",\"fulfillmentSourceId\":\"d9dd8917-996a-464d-9ad3-df72cae0c93a\",\"resourceType\":\"PRIME_MUSIC\",\"selectionSourceSessionId\":\"d9dd8917-996a-464d-9ad3-df72cae0c93a\",\"selectionSourceType\":\"ALBUM\",\"playQueueId\":\"31c0cf5c-b7a0-49eb-b1f6-40ec1f2dfcb3\",\"entityIdType\":\"ASIN\",\"entityType\":\"TRACK\",\"isExplicitLanguageFilterOn\":\"true\",\"enqueueState\":\"audio\",\"streamOrDRMTech\":\"DASH\"}",
                "actions": {
                    "next": {
                        "isAllowed": true,
                        "remainingSkips": 6
                    },
                    "previous": {
                        "isAllowed": false,
                        "disableType": "FEATURE_NOT_AVAILABLE"
                    },
                    "scrubForward": {
                        "isAllowed": false,
                        "disableType": "FEATURE_NOT_AVAILABLE"
                    },
                    "scrubBackward": {
                        "isAllowed": false,
                        "disableType": "FEATURE_NOT_AVAILABLE"
                    },
                    "loopOne": {
                        "isAllowed": false
                    },
                    "rate": {
                        "isAllowed": true
                    },
                    "queueMutations": {
                        "isAllowed": false
                    },
                    "queueView": {
                        "isAllowed": false
                    },
                    "loopAll": {
                        "isAllowed": false
                    },
                    "shuffle": {
                        "isAllowed": false
                    }
                },
                "track": {
                  ...
                }
            },
            ...
        ]
        "metadata": {
            "loopMode": "LOOP_OFF",
            "shuffleMode": "SHUFFLE_OFF",
            "playbackState": "STOPPED"
        }
    }

In this example, the client will have to disable certain transport controls, like 'previous' or 'scrubbing'. Skipping to the 'next' track is allowed, but only for another 6 skips until this customers skip limit is reached.

Subsequent calls to the event reporting and queue navigation endpoints will show a decrease in remainingSkips until eventually the action next will become disallowed.

Get Current Track

GET

/v1/playback/sessions/{sessionId}/current

Authorization Scope: [music::playback]

Retrieves a playback object for the current track.

The current track is determined by the last start event the client has sent for the track it is currently playing. Make sure the client has sent all pending start and stop events to /v1/playback/event before calling this endpoint.

Path Parameters

Name	Data Type	Required	Description
sessionId	string	Yes	The ID of the current session (from Playback object).

Example

curl --request GET '<base url>/v1/playback/sessions/<your session ID>/current' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--header 'X-Amzn-Audio-DRMType: WIDEVINE' \
--header 'X-Amzn-Audio-Device-Capability: STD_RES,HI_FI,HI_RES,THREE_DIMENSIONAL' \
--header 'X-Amzn-Device-Id: <your unique device ID>'

Response

Amazon Music response object containing:

Name	Data Type	Required	Description
data	PlaybackDataResponse	No	Playback data for the requested track.

Example

(Some lines omitted for brevity)

{
    "data": {
        "entities": [
            {
                "sessionId": "a133859e-44e6-4917-8893-fe36c8ea312a",
                "entityReferenceId": "526af97e-8396-4b5a-ae26-7ee95999d34c",
				...
                "actions": {
                    "next": {
                        "isAllowed": false,
                        "remainingSkips": 0,
                        "disableType": "NO_MORE_SKIPS"
                    },
                    "previous": {
                        "isAllowed": false,
                        "disableType": "FEATURE_NOT_AVAILABLE"
                    },
                    ...
                    "shuffle": {
                        "isAllowed": false
                    }
                },
                "track": {
                    "id": "B0BS2S4WXN",
                    "type": "Track",
                    "mediaType": "AUDIO",
                    "url": "https://...",
                    "playbackInformation": {
                        "url": "https://...",
                        "protocol": "DASH",
                        "format": "ENCRYPTED_OPUS_FLAC",
                        "licenseHeaders": {
                            ...
                        }
                    },
                    "title": "Flowers",
                    "subtitle": "Miley Cyrus - Endless Summer Vacation [Explicit]",
                    "isrc": "USSM12209777",
					...
                    ]
                }
            }
        ]
    }
}

Get Next Tracks

GET

/v1/playback/sessions/{sessionId}/next

Authorization Scope: [music::playback]

Retrieves playback objects for upcoming tracks in the queue.

Make sure the client has sent all pending start and stop events to /v1/playback/event before calling this endpoint.

Path Parameters

Name	Data Type	Required	Description
sessionId	string	Yes	The ID of the current session (from Playback object).

Query Parameters

Name	Data Type	Required	Description
limit	number	No	This sets the number of upcoming tracks to fetch in advance. Must be a number between 1 and 10 inclusive.

Example

curl --request GET '<base url>/v1/playback/sessions/<your session ID>/next?limit=5' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--header 'X-Amzn-Audio-DRMType: WIDEVINE' \
--header 'X-Amzn-Audio-Device-Capability: STD_RES,HI_FI,HI_RES,THREE_DIMENSIONAL' \
--header 'X-Amzn-Device-Id: <your unique device ID>'

Response

Amazon Music response object containing:

Name	Data Type	Required	Description
data	PlaybackDataResponse	No	Playback data for the requested tracks

Example

(Some lines omitted for brevity)

{
    "data": {
        "pageInfo": {
            "hasNextPage": true,
            "token": null
        },
        "entities": [
            {
                "sessionId": "a133859e-44e6-4917-8893-fe36c8ea312a",
                "entityReferenceId": "526af97e-8396-4b5a-ae26-7ee95999d34c",
				...
                "actions": {
                    "next": {
                        "isAllowed": false,
                        "remainingSkips": 0,
                        "disableType": "NO_MORE_SKIPS"
                    },
                    "previous": {
                        "isAllowed": false,
                        "disableType": "FEATURE_NOT_AVAILABLE"
                    },
                    ...
                    "shuffle": {
                        "isAllowed": false
                    }
                },
                "track": {
                    "id": "B0BS2S4WXN",
                    "type": "Track",
                    "mediaType": "AUDIO",
                    "url": "https://music.amazon.com/albums/B0BS2SB6RC/?trackAsin=B0BS2S4WXN&do=play&ref=dm_ff_amazonmusic.3p.debug",
                    "playbackInformation": {
                        "url": "https://d17vo8z6jop21h.cloudfront.net/api/DashDrm.mpd?dmid=200000492029992&ld=false&sd=true&hd=false&uhd=false&3d=false&ra360=false&ac4=false&mhm1=false&v=opus_flac_e&drm=wv&r=c5a68f74-1c96-46e6-a11a-c2b090316a84&rgn=NA&dtype=A3DNCSDVBULX7K",
                        "protocol": "DASH",
                        "format": "ENCRYPTED_OPUS_FLAC",
                        "licenseHeaders": {
                            "x-amz-music-rid": "c5a68f74-1c96-46e6-a11a-c2b090316a84",
                            "x-amz-music-asin": "B0BS2S4WXN",
                            "x-amz-target": "com.amazon.digitalmusiclocator.DigitalMusicLocatorServiceExternal.getLicenseForPlaybackV3",
                            "x-amz-music-device-type": "A3DNCSDVBULX7K",
                            "x-amz-music-device-id": "amzn1.application.c402f0127c5b4a839e5d7938acd958f7",
                            "x-amz-music-customer-id": "ASWQDKQ3AFS23",
                            "x-amz-music-drm-type": "WIDEVINE"
                        }
                    },
                    "title": "Flowers",
                    "subtitle": "Miley Cyrus - Endless Summer Vacation [Explicit]",
                    "isrc": "USSM12209777",
					...
                    ]
                }
            }
        ]
    }
}

Get Previous Tracks

GET

/v1/playback/sessions/{sessionId}/previous

Authorization Scope: [music::playback]

Retrieves playback objects for the previous tracks in the queue.

Make sure the client has sent all pending start and stop events to /v1/playback/event before calling this endpoint.

Path Parameters

Name	Data Type	Required	Description
sessionId	string	Yes	The ID of the current session (from Playback object).

Query Parameters

Name	Data Type	Required	Description
limit	number	No	This sets the size of the playback queue. Must be a number between 1 and 10 inclusive.

Example

curl --request GET '<base url>/v1/playback/sessions/<your session ID>/previous?limit=1' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--header 'X-Amzn-Audio-DRMType: WIDEVINE' \
--header 'X-Amzn-Audio-Device-Capability: STD_RES,HI_FI,HI_RES,THREE_DIMENSIONAL' \
--header 'X-Amzn-Device-Id: <your unique device ID>'

Response

Amazon Music response object containing:

Name	Data Type	Required	Description
data	PlaybackDataResponse	No	Playback data for the requested tracks

Example

(Some lines omitted for brevity)

{
    "data": {
        "entities": [
            {
                "sessionId": "a133859e-44e6-4917-8893-fe36c8ea312a",
                "entityReferenceId": "526af97e-8396-4b5a-ae26-7ee95999d34c",
				...
                "actions": {
                    "next": {
                        "isAllowed": false,
                        "remainingSkips": 0,
                        "disableType": "NO_MORE_SKIPS"
                    },
                    "previous": {
                        "isAllowed": false,
                        "disableType": "FEATURE_NOT_AVAILABLE"
                    },
                    ...
                    "shuffle": {
                        "isAllowed": false
                    }
                },
                "track": {
                    "id": "B0BS2S4WXN",
                    "type": "Track",
                    "mediaType": "AUDIO",
                    "url": "https://music.amazon.com/albums/B0BS2SB6RC/?trackAsin=B0BS2S4WXN&do=play&ref=dm_ff_amazonmusic.3p.debug",
                    "playbackInformation": {
                        "url": "https://d17vo8z6jop21h.cloudfront.net/api/DashDrm.mpd?dmid=200000492029992&ld=false&sd=true&hd=false&uhd=false&3d=false&ra360=false&ac4=false&mhm1=false&v=opus_flac_e&drm=wv&r=c5a68f74-1c96-46e6-a11a-c2b090316a84&rgn=NA&dtype=A3DNCSDVBULX7K",
                        "protocol": "DASH",
                        "format": "ENCRYPTED_OPUS_FLAC",
                        "licenseHeaders": {
                            "x-amz-music-rid": "c5a68f74-1c96-46e6-a11a-c2b090316a84",
                            "x-amz-music-asin": "B0BS2S4WXN",
                            "x-amz-target": "com.amazon.digitalmusiclocator.DigitalMusicLocatorServiceExternal.getLicenseForPlaybackV3",
                            "x-amz-music-device-type": "A3DNCSDVBULX7K",
                            "x-amz-music-device-id": "amzn1.application.c402f0127c5b4a839e5d7938acd958f7",
                            "x-amz-music-customer-id": "ASWQDKQ3AFS23",
                            "x-amz-music-drm-type": "WIDEVINE"
                        }
                    },
                    "title": "Flowers",
                    "subtitle": "Miley Cyrus - Endless Summer Vacation [Explicit]",
                    "isrc": "USSM12209777",
					...
                    ]
                }
            }
        ]
    }
}

Get Playback Queue

GET

/v1/playback/sessions/{sessionId}/queue

Authorization Scope: [music::playback]

Returns playback data for the current playback queue, including the tracks available through /v1/playback/sessions/{sessionId}/current and /v1/playback/sessions/{sessionId}/next.

Make sure the client has sent all pending start and stop events to /v1/playback/event before calling this endpoint.

Note that for performance reasons this endpoint will only return a reduced amount of queue metadata. It does not provide the customer actions or playback information required to download the playback assets. The endpoint is intended to serve UI rendering purposes only.

Path Parameters

Name	Data Type	Required	Description
sessionId	string	Yes	The ID of the current session (from Playback object).

Query Parameters

Name	Data Type	Required	Description
limit	number	No	This sets the number of tracks to fetch. Must be a number between 1 and 10 inclusive.

Example

curl --request GET '<base url>/v1/playback/sessions/<sessionId>/queue?limit=10' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--header 'X-Amzn-Audio-DRMType: WIDEVINE' \
--header 'X-Amzn-Audio-Device-Capability: STD_RES,HI_FI,HI_RES,THREE_DIMENSIONAL' \
--header 'X-Amzn-Device-Id: <your unique device ID>'

Responses

Amazon Music response object containing:

Name	Data Type	Required	Description
data	PlaybackDataResponse	No	Playback data for the requested tracks

Example

{
    "data": {
        "pageInfo": {
            "hasNextPage": false,
            "token": null
        },
        "entities": [
            {
                "sessionId": "388969e8-9241-4a60-a2a8-cba35a90f81",
                "entityReferenceId": "fa22ab8f-c5f7-493e-8dcb-2295decf3c0",
                "actions": {},
                "track": {
                    "id": "B08KC1C6BF",
                    "_type": "Track",
                    "mediaType": "AUDIO",
                    "url": "https://music.amazon.com.mx/albums/B08KBXTZ7X/?trackAsin=B08KC1C6BF&do=play&ref=abc",
                    "previewUrl": null,
                    "title": "Cornfield Chase",
                    "subtitle": "Hans Zimmer - Interstellar (Original Motion Picture Soundtrack) [Expanded Edition]",
                    "isrc": "USNLR1400774",
                    "images": [
                        {
                            "url": "https://m.media-amazon.com/images/I/A1smtRIAUvL.jpg"
                        }
                    ],
                    "duration": 127,
                    "album": {
                        "id": "B08KBXTZ7X",
                        "title": "Interstellar (Original Motion Picture Soundtrack) [Expanded Edition]"
                    },
                    "artists": [
                        {
                            "id": "B000QJK5EQ",
                            "name": "Hans Zimmer"
                        }
                    ]
                }
            },
            {
                ...
            }
        ]
    }
}

Get Active Sessions

GET

/v1/playback/sessions/active

Authorization Scope: [music::playback]

Retrieve all playback sessions across all devices.

Example

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

Response

Amazon Music response object containing:

Name	Data Type	Required	Description
data	PlaybackSessionResponse	No	Response containing a list of active playback sessions for the current user.

Example

(Some lines omitted for brevity)

{
    "data": {
        "sessions": [
            {
                "sessionId": "8f48fc53-b52a-4b68-950b-020fe89e3b46",
                "entityReferenceId": "e9c5ad6c-ebba-4c38-966d-c5b5b66ddfa4",
                "track": {
                    "id": "B084KPC3Q7",
                    "_type": "Track",
                    "mediaType": "AUDIO",
                    "url": "https://music.amazon.com/albums/B084KP4NBH/?trackAsin=B084KPC3Q7&do=play&ref=dm_ff_amazonmusic.3p",
                    "previewUrl": "https://music.amazon.com/getSampleTrack/B084KPC3Q7?ref=dm_ff_amazonmusic.3p",
                    "title": "Selfless",
                    "subtitle": "The Strokes - The New Abnormal [Explicit]",
                    ...
                },
                "metadata": {
                    "loopMode": "LOOP_OFF",
                    "shuffleMode": "SHUFFLE_OFF",
                    "playbackState": "PLAYING"
                }
            }
        ]
    }
}

Restore Playback Session

GET

/v1/playback/sessions/{sessionId}/entities/{entityReferenceId}

Authorization Scope: [music::playback]

Used to retrieve an inactive playback session as long as it has been active within the last 30 days. Can also be used to refresh the data inside the queue of the current session.

Path Parameters

Name	Data Type	Required	Description
sessionId	string	Yes	The ID of the session to retrieve (from Playback object).
entityReferenceId	string	Yes	The ID of the playback queue entity last played.

Query Parameters

Name	Data Type	Required	Description
limit	number	No	This sets the number of tracks to fetch. Must be a number between 1 and 10 inclusive.

Example

curl --request GET '<base url>/v1/playback/sessions/<sessionId>/entities/<entityReferenceId>?limit=5' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--header 'X-Amzn-Audio-DRMType: WIDEVINE' \
--header 'X-Amzn-Audio-Device-Capability: STD_RES,HI_FI,HI_RES,THREE_DIMENSIONAL' \
--header 'X-Amzn-Device-Id: <your unique device ID>'

Response

Amazon Music response object containing:

Name	Data Type	Required	Description
data	InitialPlaybackSessionResponse	Yes	Playback session object

Example

(Some lines omitted for brevity)

{
    "data": {
        "pageInfo": {
            "hasNextPage": false
        },
        "entities": [
            {
                "sessionId": "8f48fc53-b52a-4b68-950b-020fe89e3b46",
                "entityReferenceId": "a6e35026-7d23-4a54-8b2c-6854d8a107ee",
                "metricId": "{\"entityId\":\"B084KW75Z6\",\"playbackInstanceId\":\"a6e35026-7d23-4a54-8b2c-6854d8a107ee\",\"metricsSpec\":\"TRACK\",\"selectionSourceSessionId\":\"8f48fc53-b52a-4b68-950b-020fe89e3b46\",\"resourceType\":\"UNLIMITED_MUSIC\",\"playQueueId\":\"8f48fc53-b52a-4b68-950b-020fe89e3b46\",\"selectionSourceId\":\"B084KYMDXT\",\"trackCount\":\"1\",\"selectionSourceType\":\"ALBUM\",\"entityIdType\":\"ASIN\",\"entityType\":\"TRACK\",\"isExplicitLanguageFilterOn\":\"true\",\"enqueueState\":\"audio\",\"streamOrDRMTech\":\"DASH\"}",
                "actions": {
                    "next": {
                        "isAllowed": true
                    },
                    "previous": {
                        "isAllowed": true
                    },
                    "scrubForward": {
                        "isAllowed": true
                    },
                    "scrubBackward": {
                        "isAllowed": true
                    },
                    "loopOne": {
                        "isAllowed": true
                    },
                    "rate": {
                        "isAllowed": false
                    },
                    "queueMutations": {
                        "isAllowed": true
                    },
                    "queueView": {
                        "isAllowed": true
                    },
                    "loopAll": {
                        "isAllowed": true
                    },
                    "shuffle": {
                        "isAllowed": true
                    }
                },
                "track": {
                    "id": "B084KW75Z6",
                    "_type": "Track",
                    "mediaType": "AUDIO",
                    "url": "https://music.amazon.com/albums/B084KP4NBH/?trackAsin=B084KW75Z6&do=play&ref=dm_ff_amazonmusic.3p",
                    "playbackInformation": {
                        "url": "https://d17vo8z6jop21h.cloudfront.net/api/DashDrm.mpd?dmid=200000347977163&ld=true&sd=true&hd=true&uhd=true&3d=true&ra360=false&ac4=false&mhm1=false&v=opus_flac_e&drm=wv&r=c0b137a6-d8d8-44ed-a410-00f3a559591c&rgn=NA&dtype=A3PMWP4IZPXWSV",
                        "protocol": "DASH",
                        "format": "ENCRYPTED_OPUS_FLAC",
                        "licenseUrl": null,
                        "licenseHeaders": {
                            "x-amz-music-rid": "c0b137a6-d8d8-44ed-a410-00f3a559591c",
                            "x-amz-music-asin": "B084KW75Z6",
                            "x-amz-target": "com.amazon.digitalmusiclocator.DigitalMusicLocatorServiceExternal.getLicenseForPlaybackV3",
                            "x-amz-music-device-type": "A3PMWP4IZPXWSV",
                            "x-amz-music-device-id": "defd7da3-bfe1-4e30-93a7-e7d6c3962c63",
                            "x-amz-music-customer-id": "A2UVA8V9BOYUMQ",
                            "x-amz-music-drm-type": "WIDEVINE"
                        },
                        "applicationCertificate": null,
                        "progressMilliseconds": null
                    },
                    "title": "The Adults Are Talking [Explicit]",
                    "subtitle": "The Strokes - The New Abnormal [Explicit]",
                    "isrc": "USRC11902726",
                    "images": [
                        {
                            "url": "https://m.media-amazon.com/images/I/91hcERG6MkL.jpg"
                        }
                    ],
                    "duration": 309,
                    "album": {
                        "id": "B084KP4NBH",
                        "title": "The New Abnormal [Explicit]"
                    },
                    "artists": [
                        {
                            "id": "B00G70DLAS",
                            "name": "The Strokes"
                        }
                    ]
                }
            },
            ...
        ],
        "metadata": {
            "loopMode": "LOOP_OFF",
            "shuffleMode": "SHUFFLE_OFF",
            "playbackState": "PLAYING"
        }
    }
}

Queue Next Track

POST

/v1/playback/sessions/{sessionId}/queue/next

Authorization Scope: [music::playback]

Insert a track into the playback queue immediately after the current track.

Path Parameters

Name	Data Type	Required	Description
sessionId	string	Yes	The ID of the current session (from Playback object).

Request Parameters

Name	Data Type	Required	Description
playParams.id	string	Yes	The ID (MRN format) of the item to be added.

Example

curl --request POST '<base url>/v1/playback/sessions/<sessionId>/queue/next' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--data '{
    "playParams": {
        "id": "mrn:1.0:catalog:track:asin:B084KPC3Q7"
    }
}'

Responses

HTTP status 201 on success.

The client is required to update its queue using /v1/playback/sessions/{sessionId}/next from current position since the next position may have changed.

Queue Last Track

POST

/v1/playback/sessions/{sessionId}/queue/last

Authorization Scope: [music::playback]

Add a track to the end of the playback queue.

Path Parameters

Name	Data Type	Required	Description
sessionId	string	Yes	The ID of the current session (from Playback object).

Request Parameters

Name	Data Type	Required	Description
playParams.id	string	Yes	The ID (MRN format) of the item to be added.

Example

curl --request POST '<base url>/v1/playback/sessions/<sessionId>/queue/last' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--data '{
    "playParams": {
        "id": "mrn:1.0:catalog:track:asin:B084KPC3Q7"
    }
}'

Responses

HTTP status 201 on success.

The client may need to update its queue using /v1/playback/sessions/{sessionId}/next from current position since the next position may have changed.

Set Playback Mode to Loop

PUT

/v1/playback/sessions/{sessionId}/loop

Authorization Scope: [music::playback]

Set the playback queue to loop the current track.

Path Parameters

Name	Data Type	Required	Description
sessionId	string	Yes	The ID of the current session (from Playback object).

Request Parameters

Name	Data Type	Required	Description
loopMode	string	Yes	Enable or disable loop mode. Allowed values are 'LOOP_ONE', 'LOOP_ALL', and 'LOOP_OFF'

Example

curl --request PUT '<base url>/v1/playback/sessions/<sessionId>/loop' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--data '{
    "loopMode": "LOOP_ALL"
}'

Responses

HTTP status 200 on success.

The client is required to update its queue using /v1/playback/sessions/{sessionId}/next from current position since the next position may have changed.

Set Playback Mode to Shuffle

PUT

/v1/playback/sessions/{sessionId}/shuffle

Authorization Scope: [music::playback]

Set the playback queue to shuffle the upcoming tracks.

Path Parameters

Name	Data Type	Required	Description
sessionId	string	Yes	The ID of the current session (from Playback object).

Request Parameters

Name	Data Type	Required	Description
body.shuffleMode	string	Yes	Enable or disable shuffle mode. Allowed values are 'SHUFFLE_ON' and 'SHUFFLE_OFF'

Example

curl --request PUT '<base url>/v1/playback/sessions/<sessionId>/shuffle' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--data '{
    "shuffleMode": "SHUFFLE_ON"
}'

Responses

HTTP status 200 on success.

The client is required to update its queue using /v1/playback/sessions/{sessionId}/next from current position since the next position may have changed.

Report Single Event

POST

/v1/playback/event

Authorization Scope: [music::playback]

Report a single playback event to the Amazon Music service.

Body Parameters

Name	Data Type	Required	Description
metricId	string	Yes	The metric ID to report. Pick the identifier associated with the current playqueue entry.
event	PlaybackEventStart \| PlaybackEventStop	Yes	The event object, containing details about the reported playback event.
options.takeOverType	object	No	Concurrency handling strategy. Allowed values are 'AUTO' and 'FORCE'. Only applicable when sending 'start' type events.

Event fields

Name	Data Type	Required	Description
type	string	Yes	The type of event, which can either be `start` or `stop`.
clientTimestampInMilliseconds	integer	Yes	The client's current time in milliseconds since the UNIX epoch (January 1, 1970 00:00:00 UTC)
initialPlaybackDelayMilliseconds	integer	Yes	Time between when a customer expects to hear music (or stop hearing music) and when playback actually starts (or stops).
deviceTimezone	string	Yes	The device timezone, measured in offset hours. For example, `-08:00` is the timezone of California.
playbackCurrentSpeed	double	Yes	Current playback speed factor. For example, `1.0` describes regular playback, and `1.25` is 25% faster.

Only for start events

Name	Data Type	Required	Description
playbackStartAbsoluteOffsetMilliseconds	integer	Yes	Absolute offset in milliseconds from where the playback starts within a track. The value can range from `0` to the total duration of a track.

Only for stop events

Name	Data Type	Required	Description
durationSeconds	integer	Yes	Playback duration in seconds since the start of the track or since the last interruption.
entityProgressSeconds	integer	Yes	The current absolute playback position within this track. If the track does not complete, report the farthest point in the progress bar.
rebufferCount	integer	Yes	Number of times, playback was interrupted since the last start event due to rebuffering.
terminationReason	string	Yes	Reason for why playback was terminated. Valid values are: `userStop`, `userNext`, `userPrev`, `trackFinished`, `trackScrub`, `systemStop`

terminationReason

If the user skips next or previous, the client should emit a stop event for the current track with an appropriate reason such as userNext or userPrev.
If the user scrubs, emit a stop event with trackScrub.
If the current track is paused, emit userStop.
If the current track finishes playing, emit trackFinished.
For any other reason for interruption, emit systemStop.

Example start event

curl --request POST '<base url>/v1/playback/event' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: <your auth token>' \
--header 'X-Amzn-Audio-DRMType: WIDEVINE' \
--header 'X-Amzn-Audio-Device-Capability: STD_RES,HI_FI,HI_RES,THREE_DIMENSIONAL' \
--header 'X-Amzn-Device-Id: <your unique device ID>' \
--header 'Content-Type: application/json' \
--data '{
    "metricId": "{\"entityId\":\"B084KW75Z6\",\"playbackInstanceId\":\"84c44b4e-48ce-47f8-936f-7f3fd7dcb867\",\"metricsSpec\":\"TRACK\",\"resourceType\":\"UNLIMITED_MUSIC\",\"selectionSourceId\":\"B084KYMDXT\",\"trackCount\":\"1\",\"playQueueId\":\"849863cc-bee2-4d3c-9d69-bdaca8a37073\",\"selectionSourceType\":\"ALBUM\",\"selectionSourceSessionId\":\"849863cc-bee2-4d3c-9d69-bdaca8a37073\",\"entityIdType\":\"ASIN\",\"entityType\":\"TRACK\",\"isExplicitLanguageFilterOn\":\"true\",\"enqueueState\":\"audio\",\"streamOrDRMTech\":\"DASH\"}",
    "event": {
        "type": "start",
        "clientTimestampInMilliseconds": 1716493161481,
        "initialPlaybackDelayMilliseconds": 571,
        "deviceTimezone": "+02:00",
        "playbackCurrentSpeed": 1.0,
        "playbackStartAbsoluteOffsetMilliseconds": 0
    },
    "options": {
        "takeOverType": "AUTO"
    }
}'

Example stop event

curl --request POST '<base url>/v1/playback/event' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: <your auth token>' \
--header 'X-Amzn-Audio-DRMType: WIDEVINE' \
--header 'X-Amzn-Audio-Device-Capability: STD_RES,HI_FI,HI_RES,THREE_DIMENSIONAL' \
--header 'X-Amzn-Device-Id: <your unique device ID>' \
--header 'Content-Type: application/json' \
--data '{
    "metricId": "{\"entityId\":\"B084KW75Z6\",\"playbackInstanceId\":\"84c44b4e-48ce-47f8-936f-7f3fd7dcb867\",\"metricsSpec\":\"TRACK\",\"resourceType\":\"UNLIMITED_MUSIC\",\"selectionSourceId\":\"B084KYMDXT\",\"trackCount\":\"1\",\"playQueueId\":\"849863cc-bee2-4d3c-9d69-bdaca8a37073\",\"selectionSourceType\":\"ALBUM\",\"selectionSourceSessionId\":\"849863cc-bee2-4d3c-9d69-bdaca8a37073\",\"entityIdType\":\"ASIN\",\"entityType\":\"TRACK\",\"isExplicitLanguageFilterOn\":\"true\",\"enqueueState\":\"audio\",\"streamOrDRMTech\":\"DASH\"}",
    "event": {
        "type": "stop",
        "clientTimestampInMilliseconds": 1716493236481,
        "initialPlaybackDelayMilliseconds": 0,
        "deviceTimezone": "+02:00",
        "playbackCurrentSpeed": 1.0,
        "durationSeconds": 75,
        "entityProgressSeconds": 75,
        "rebufferCount": 0,
        "terminationReason": "userStop"
    }
}'

Responses

HTTP status 201 on success.

HTTP status 422 on start type events if a concurrency error has been detected that requires user interaction for resolution.

Concurrency Error Handling

The /v1/playback/event endpoint supports 2 concurrency handling options that clients can use to resolve playback conflicts.

With takeOverType: AUTO specified in the start event request body, the client delegates concurrency resolution to the backend. When a playback conflict occurs, the backend will attempt to automatically take precedence over the other device concurrently streaming and to start the new playback session on the current device. This allows for uninterrupted listening without UI disruption. In rare cases, e.g. when the other device is competing with the same take-over strategy, the event endpoint will still return a 422 error response (TAKE_OVER_DEVICE_STREAMING_ERROR) to the client.

{
    "status": 422,
    "code": "TAKE_OVER_DEVICE_STREAMING_ERROR",
    "message": "Failed to take over device streaming.",
    "reference": "f9637f25-5e13-4d68-98e7-2378af5469a7"
}

Without takeOverType: AUTO, concurrency conflicts will always return a 422 error response (MAX_CONCURRENCY_REACHED) to a start event request to the client. The client can then decide how to resolve the conflict - either by displaying a prompt to take over the session, or by stopping the new playback attempt. If the client ignores the concurrency error, playback will fail after a certain number of preloaded tracks.

{
    "status": 422,
    "code": "MAX_CONCURRENCY_REACHED",
    "message": "Maximum number of concurrent listening is reached.",
    "reference": "5cb76055-be81-4cce-8b41-732c11bbc944"
}

To force a takeover after seeing a concurrency error, the client can re-send the /v1/playback/event request with the takeOverType: FORCE option. This will make the backend take over the existing stream for the current device and instruct the other device to terminate playback.

In summary, takeOverType: AUTO handles concurrency resolution automatically for most cases, while takeOverType: FORCE provides a way to explicitly take over after initially seeing a concurrency error. Clients can choose one or the other to best fit their playback and UI needs.

Report Multiple Events

POST

/v1/playback/events

Authorization Scope: [music::playback]

Report multiple playback events to the Amazon Music service within a single HTTP request.

Body Parameters

Name	Data Type	Required	Description
events[].metricId	string	Yes	The metric ID to report. Pick the identifier associated with the playqueue entry the event relates to.
events[].event	object	Yes	The event object, containing details about the reported playback event.
options.takeOverType	object	No	Concurrency handling strategy. Allowed values are 'AUTO' and 'FORCE'.

Example request

curl --request POST '<base url>/v1/playback/events' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: <your auth token>' \
--header 'X-Amzn-Audio-DRMType: WIDEVINE' \
--header 'X-Amzn-Audio-Device-Capability: STD_RES,HI_FI,HI_RES,THREE_DIMENSIONAL' \
--header 'X-Amzn-Device-Id: <your unique device ID>' \
--header 'Content-Type: application/json' \
--data '{
    "events": [
        {
            "metricId": "{\"entityId\":\"B084KW75Z6\",\"playbackInstanceId\":\"a6e35026-7d23-4a54-8b2c-6854d8a107ee\",\"metricsSpec\":\"TRACK\",\"selectionSourceSessionId\":\"8f48fc53-b52a-4b68-950b-020fe89e3b46\",\"resourceType\":\"UNLIMITED_MUSIC\",\"playQueueId\":\"8f48fc53-b52a-4b68-950b-020fe89e3b46\",\"selectionSourceId\":\"B084KYMDXT\",\"trackCount\":\"1\",\"selectionSourceType\":\"ALBUM\",\"entityIdType\":\"ASIN\",\"entityType\":\"TRACK\",\"isExplicitLanguageFilterOn\":\"true\",\"enqueueState\":\"audio\",\"streamOrDRMTech\":\"DASH\"}",
            "event": {
                "type": "stop",
                "clientTimestampInMilliseconds": 1732718286,
                "initialPlaybackDelayMilliseconds": 0,
                "deviceTimezone": "+02:00",
                "playbackCurrentSpeed": 1.0,
                "durationSeconds": 241,
                "entityProgressSeconds": 241,
                "rebufferCount": 0,
                "terminationReason": "trackFinished"
            }
        },
        {
            "metricId": "{\"entityId\":\"B084KPC3Q7\",\"playbackInstanceId\":\"e9c5ad6c-ebba-4c38-966d-c5b5b66ddfa4\",\"metricsSpec\":\"TRACK\",\"selectionSourceSessionId\":\"8f48fc53-b52a-4b68-950b-020fe89e3b46\",\"resourceType\":\"UNLIMITED_MUSIC\",\"playQueueId\":\"8f48fc53-b52a-4b68-950b-020fe89e3b46\",\"selectionSourceId\":\"B084KYMDXT\",\"trackCount\":\"1\",\"selectionSourceType\":\"ALBUM\",\"entityIdType\":\"ASIN\",\"entityType\":\"TRACK\",\"isExplicitLanguageFilterOn\":\"true\",\"enqueueState\":\"audio\",\"streamOrDRMTech\":\"DASH\"}",
            "event": {
                "type": "start",
                "clientTimestampInMilliseconds": 1732718347,
                "initialPlaybackDelayMilliseconds": 61,
                "deviceTimezone": "+02:00",
                "playbackCurrentSpeed": 1.0,
                "playbackStartAbsoluteOffsetMilliseconds": 0
            }
        }
    ],
    "options": {
        "takeOverType": "AUTO"
    }
}'

Responses

HTTP status 201 on success.

HTTP status 422 on concurrency errors.