Handle Pagination in API Query Results

Many Alexa REST APIs that potentially return many results are paginated. They return a subset, or "page," of results and a paginationContext object with information about how to get the next page of results. The following example shows a paginationContext object in a general format:

{
   "paginationContext": {
      "nextToken": "{token}"
   },
   "results": [
      {
      ...
      }
   ]
}

The following table shows the fields contained in the paginationContext object.

Field Description Type Required

nextToken

A token to retrieve additional results. If not present, there are no more results.

string

No

Limit page size

To limit page size, set maxResults in your request to the number of results to retrieve.

For a GET method, provide maxResults as a query parameter as shown in the following example:

   GET /{resources}?maxResults=10

For a POST request, include a paginationContext object with the maxResults property in the request body.

{
    ...
    "paginationContext": {
        "maxResults": 2
    }
}

Request the next page of results

After you request a page of results, you must then send a new request to get the next page of results. Your new request should be the same as the previous request, with the addition of a nextToken parameter set to the nextToken value in the response you received from your previous request.

The response contains results starting from this token and includes the nextToken value only if there are further results.

The following table shows the parameter fields for limiting page size and requesting the next page of results. If the original request was a GET request, pass these values as query parameters. If the original request was a POST request, include a paginationContext object with these properties in the request body.

Field Description Type Required

maxResults

Maximum number of results to be returned in the response body. Must be greater than zero and less than or equal to 10.

number (integer)

Yes

nextToken

Token to retrieve a specific page of the paginated results. If this token isn't present, the response contains the first page of results.

string

No

Pagination example for a GET method

The following example shows a GET request for the List units operation in the Property Hierarchy Management REST API. In this example, the response for a previous call to this operation included a value in the paginationContext.nextToken property, indicating that there were more results. For a GET method, provide the nextToken in the query parameters for the request.

Copied to clipboard.

GET /v2/units?parentId={unitId}&expand=all&nextToken={nextTokenValue} HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer {access token}.

Pagination example for a POST method

The following example shows a POST request for the Get skill enablement for multiple units operation in the Skill Management API. In this example, the response for a previous call to this operation included a value in the paginationContext.nextToken property, indicating that there were more results. For a POST method, provide the nextToken in the request body.

Request:

Copied to clipboard.

POST /v1/skills/enablements/batchGet HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request body:

Copied to clipboard.

{
  "items": [
    {
      "itemId": 0,
      "unitId": "amzn1.alexa.unit.did.AAA"
    },
    {
      "itemId": 1,
      "unitId": "amzn1.alexa.unit.did.BBB"
    }
  ],
  "paginationContext": {
      "nextToken": "eJy..."
  }
}

Amazon request ID

In some REST APIs, Alexa includes the X-Amzn-RequestId parameter in the response header. If a problem occurs, Amazon can use the request-id to help troubleshoot problems. For example, the response might contain the following header:

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Parameter Description Type

request-id

Unique identifier for the request.

String

Was this page helpful?

Last updated: Oct 31, 2024