Amazon Music Web API
Web API Sparse Fieldsets V2.0
Web API V2 Sparse Fieldsets
Amazon Music Web API V2 lets you request only the fields you need using sparse fieldsets. Selecting fewer fields reduces payload size and improves latency.
Syntax
A sparse fieldset is a query parameter of the form:
fields[<type>]=comma,separated,field,names
The <type> names the entity type whose fields you are selecting, and the value is a comma-separated list of field names on that type.
curl --location '<base url>/v2/albums?ids=B0064UPU4G&fields[album]=title,id&fields[artist]=name' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>'
Selecting nested entities
Fieldsets are applied per entity type. To shape a nested entity, add a separate fields[<type>] parameter for that nested type. For example, to return only an album's title, id, and artists, and only each artist's name:
fields[album]=title,id,artists&fields[artist]=name
{
"id": "B073J5NW51",
"title": "Sound Awake",
"artists": [
{ "id": "B000X6FP38", "name": "Karnivool" }
]
}
Entity types
The following fields[<type>] parameters appear across the V2 reference:
fields[album], fields[artist], fields[image], fields[track], fields[view], fields[entityGroup], fields[playlist], fields[podcastShow], and fields[podcastEpisode].
Not every endpoint supports every type — each reference page lists the fieldset parameters it accepts. Rely on those per-endpoint lists rather than assuming a type is available everywhere.
Fieldsets on playback endpoints
The Playback APIs also support sparse fieldsets, using their own domain-specific parameters — fields[playableEntity] (to request stream URL and DRM information), fields[entityControls], and fields[queueControls]. See Playback API Concepts and the Playback reference for the values each accepts.
Errors
Requesting a field that does not exist on the named type returns a 400 BAD_REQUEST:
{
"error": {
"code": "BAD_REQUEST",
"message": "Invalid field 'nonexistent' for type 'album'",
"traceId": "1-abc-def"
}
}
See Errors for the full error shape.
