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, add a maxResults query parameter to your request as shown in the following example:

   GET /{resources}?maxResults=10

Request the next page of results

After you request a page of results, you must then send a new GET 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 query 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.

Request query parameters for limiting page size and requesting the next page of results

The following table shows the query parameter fields for limiting page size and requesting the next page of results.

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

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