Amazon Music Web API
Web API Pagination V2.0
Web API V2 Pagination
Amazon Music Web API V2 collections use forward-only cursor pagination. You request a page size and, when more results exist, the response hands back an opaque cursor that you pass on the next request to fetch the following page.
Two query parameters control paging:
first— the number of items to return. The default page size is20; the maximum is100.after— the cursor to continue from, taken from the previous response.
List endpoints
Most collection endpoints (for example, GET /v2/albums/top and GET /v2/albums/new-releases) return a page object with an items array and a top-level nextToken:
{
"items": [
{
"id": "B084KP4NBH",
"title": "The New Abnormal",
"releaseDate": "2020-04-10T00:00:00.000Z"
}
],
"nextToken": "B0EXAMP240"
}
Pass the nextToken value back as after to fetch the next page:
curl --location '<base url>/v2/albums/top?first=20&after=B0EXAMP240' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>'
When nextToken is absent from the response, you have reached the last page of the collection.
Views endpoints paginate differently
This is the difference partners most often get wrong. The Views APIs do not return a top-level nextToken. Instead, a view's cursor lives at content.nextPageToken, and forward paging with first/after advances across the view's top-level entityGroups array:
{
"id": "B0EXAMP700",
"content": {
"entityGroups": [
{
"id": "B0EXAMP710",
"title": "Playlists for You",
"content": {
"entities": [ /* ... */ ],
"nextPageToken": "B0EXAMP720"
}
}
],
"nextPageToken": "B0EXAMP730"
}
}
- To page across the groups in a view, use the view's top-level
content.nextPageTokenas youraftervalue. - To page within a single group — a "See All" — call that view's group endpoint with the group's
groupId(for example,GET /v2/views/home/{groupId}). ThegroupIdis an opaque token taken from a prior view response. See Using the Views APIs for the full pattern.
Errors
Requesting a page size outside the allowed range returns a 400 BAD_REQUEST:
{
"error": {
"code": "BAD_REQUEST",
"message": "first parameter must be between 1 and 100",
"traceId": "1-abc-def"
}
}
See Errors for the full error shape.
What cursor pagination does not provide
Cursors are opaque — do not parse, decode, or construct them; treat each nextToken (or nextPageToken) purely as a token to echo back. Paging is forward-only. There are no backward cursors, no numeric offsets, no page numbers, and no total-count field. Iterate by following the cursor until it is absent.
