Intent Request History REST API Reference

Use the Intent Request History REST API to get the aggregated and anonymized transcriptions of user speech data and intent request details for a skill. The API returns data from customer interactions over the past 30 days, updated each day. You can use the data to learn how users interact with your skill to identify improvements to your interaction model.

This API supports text search and sort on the results. Data is available for skills that have at least 10 unique users per locale in a day. Alexa returns data for those locales that meet the threshold only.

You can view intent history in the Alexa developer console also. For details, see Review the Intent History for a Custom Skill. Or, you can view intent history by using the Alexa Skills Kit (ASK) Command Line Interface get-utterance-data command.

API endpoint

The endpoint of the Intent Request History API is https://api.amazonalexa.com.

Authentication

Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA). For details, see Get an Access Token for SMAPI.

Operations

The Intent Request History API includes the following operations.

Operation HTTP method and URI

Get utterance data

GET /v1/skills/{skillId}/history/intentRequests?maxResults={maxResults}&nextToken={nextToken}&sortDirection={sortDirection}&sortField={sortField}&dialogAct.name={dialogAct.name}&intent.confidence.bin={intent.confidence.bin}&intent.name={intent.name}&intent.slots.name={intent.slots.name}&interactionType={interactionType}&locale={locale}&publicationStatus={publicationStatus}&stage={stage}&utteranceText={utteranceText}

Get utterance data

Get the utterance data for the last 30 days. You can define the sort and filter criteria based on a combination of attributes to sort and filter the intent history results.

Request

To get utterance data, you make a GET request to the householdlists resource.

Request path and header example

Copied to clipboard.

GET /v1/skills/{skillId}/history/intentRequests?maxResults={maxResults}&nextToken={nextToken}&sortDirection={sortDirection}&sortField={sortField}&dialogAct.name={dialogAct.name}&intent.confidence.bin={intent.confidence.bin}&intent.name={intent.name}&intent.slots.name={intent.slots.name}&interactionType={interactionType}&locale={locale}&publicationStatus={publicationStatus}&stage={stage}&utteranceText={utteranceText}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter Located in Description Type Required

skillId

Path

Identifies the skill.
Valid values: 1 – 255 characters.

String

Yes

maxResults

Query

Maximum number of results to return in the response.
Valid values: 1–250. Default: 10.

Integer

No

nextToken

Query

Token from the previous response. If not included, the Alexa service returns the first page of results.
Include if iterating over a paginated response.

String

No

sortDirection

Query

Set the sorting direction of the results as ascending or descending order.
Valid values: asc, desc. Default: desc.

String

No

sortField

Query

Sort the result on the specified field in alphabetical order.
Valid values: dialogAct.name, intent.confidence.bin, intent.name, interactionType, locale, publicationStatus, recordCount, stage, utteranceText.

String

No

dialogAct.name

Query

Filter based on dialog directives used in multi-turn conversations. For more details about the Dialog directive and multi-turn conversations, see Dialog Interface Reference. You can specify this filter more than one time in a request.
Valid values: Dialog.ElicitSlot, Dialog.ConfirmSlot, Dialog.ConfirmIntent.

String

No

intent.confidence.bin

Query

Filter based on the confidence that the utterance resolved to the correct intent. Alexa doesn't send low confidence requests to your skill. You can specify this filter more than one time in a request.
Valid values: HIGH, MEDIUM, LOW.

String

No

intent.name

Query

Filter based on the specified intent. You can specify this filter more than one time in a request.
Valid values: Any string without white spaces.

String

No

intent.slots.name

Query

Filter based on the specified slot name. You can specify this filter more than one time in a request.
Valid values: Any string without white spaces.

String

No

interactionType

Query

Filter based on whether the user invoked the skill and stated the intent in a single phrase (one shot), or the user invoked the skill first, and then stated the intent (modal).
Valid values: ONE_SHOT, MODAL.

String

No

locale

Query

Filter the results based on the specified locale where the interaction occurred. You can specify this filter more than one time in a request.
Valid values: All locales supported for custom skills, such as en-US.

String

No

publicationStatus

Query

Filter based on the publication status of the skill when the interaction occurred.
Valid values: CERTIFICATION, DEVELOPMENT.

String

No

stage

Query

Filter based on the stage of the skill. Until you publish your skill, set to development.
Valid values: development, live.

String

No

utteranceText

Query

Filter results based on whether the specified phrase is in the utterance. For example, the%20answer%20is. You can specify this filter more than one time.
Valid values: Any string without white space up to 100 characters.

String

No

access token

Header

LWA token.

String

Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with a list of utterances that match the specified filter criteria. The results include a subset of utterances sent to your skill, filtered to include frequent utterances that meet the daily user threshold. The response might not contain any utterances.

On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The following example shows a response sorted on the intent.confidence.bin field in descending order.

{
    "body": {
        "_links": {
            "self": {
                "href": "v1/skills/amzn1.ask.skill.1/history/intentRequests?nextToken=someToken1&maxResults=5&sortDirection=desc&sortField=intent.confidence.bin&locale=en-US&locale=en-GB&locale=de-DE&intent.confidence.bin=HIGH&intent.confidence.bin=MEDIUM&stage=development&publicationStatus=CERTIFICATION&dialogAct.name=Dialog.ElicitSlot&dialogAct.name=Dialog.ConfirmSlot&intent.slots.name=answer&utteranceText=answer&intent.name=AnswerIntent&interactionType=MODAL"
            },
            "next": {
                "href": "v1/skills/amzn1.ask.skill.1/history/intentRequests?nextToken=someToken2&maxResults=5&sortDirection=desc&sortField=intent.confidence.bin&locale=en-US&locale=en-GB&locale=de-DE&intent.confidence.bin=HIGH&intent.confidence.bin=MEDIUM&stage=development&publicationStatus=CERTIFICATION&dialogAct.name=Dialog.ElicitSlot&dialogAct.name=Dialog.ConfirmSlot&intent.slots.name=answer&utteranceText=answer&intent.name=AnswerIntent&interactionType=MODAL"
            }
        },
        "isTruncated": true,
        "nextToken": "someToken.1",
        "totalCount": 15,
        "startIndex": 0,
        "skillId": "amzn1.ask.skill.1",
        "items": [{
                "dialogAct": {
                    "name": "Dialog.ConfirmSlot"
                },
                "intent": {
                    "name": "AnswerIntent",
                    "confidence": {
                        "bin": "HIGH"
                    },
                    "slots": {
                        "answer": {
                            "name": "answer"
                        }
                    }
                },
                "locale": "en-GB",
                "interactionType": "MODAL",
                "stage": "development",
                "publicationStatus": "CERTIFICATION",
                "utteranceText": "the answer is k"
            },
            {
                "dialogAct": {
                    "name": "Dialog.ConfirmSlot"
                },
                "intent": {
                    "name": "AnswerIntent",
                    "confidence": {
                        "bin": "HIGH"
                    },
                    "slots": {
                        "answer": {
                            "name": "answer"
                        }
                    }
                },
                "locale": "en-GB",
                "interactionType": "MODAL",
                "stage": "development",
                "publicationStatus": "CERTIFICATION",
                "utteranceText": "ask game trivia the answer is elephant"
            },
            {
                "dialogAct": {
                    "name": "Dialog.ElicitSlot"
                },
                "intent": {
                    "name": "AnswerIntent",
                    "confidence": {
                        "bin": "HIGH"
                    },
                    "slots": {
                        "answer": {
                            "name": "answer"
                        }
                    }
                },
                "locale": "en-US",
                "interactionType": "MODAL",
                "stage": "development",
                "publicationStatus": "CERTIFICATION",
                "utteranceText": "the answer is apollo"
            },
            {
                "dialogAct": {
                    "name": "Dialog.ConfirmSlot"
                },
                "intent": {
                    "name": "AnswerIntent",
                    "confidence": {
                        "bin": "MEDIUM"
                    },
                    "slots": {
                        "answer": {
                            "name": "answer"
                        }
                    }
                },
                "locale": "en-US",
                "interactionType": "MODAL",
                "stage": "development",
                "publicationStatus": "CERTIFICATION",
                "utteranceText": "the answer is tetris"
            },
            {
                "dialogAct": {
                    "name": "Dialog.ConfirmSlot"
                },
                "intent": {
                    "name": "AnswerIntent",
                    "confidence": {
                        "bin": "MEDIUM"
                    },
                    "slots": {
                        "answer": {
                            "name": "answer"
                        }
                    }
                },
                "locale": "en-US",
                "interactionType": "MODAL",
                "stage": "development",
                "publicationStatus": "CERTIFICATION",
                "utteranceText": "the answer is washington d. c."
            }
        ]
    }
}

Response body properties

Property Description Type

_links

Links for item navigation.
Defined in JSON Hypertext Application Language specification.

_links object

isTruncated

Indicates whether there are more items to return. If set to true, include nextToken a subsequent request. Or, you can get the remaining items by using the next link in the _links object.

Boolean

nextToken

(Optional) Included when there are more results to return. Use this value in a subsequent request.

String

totalCount

Total number of results that matched the query.

Integer

startIndex

Position of the current page in the result set.

Integer

skillId

Identifies the skill to which the intent request history data applies.

String

items[]

Filtered list of intent requests for the skill.

Array of objects

items.dialogAct.name

Dialog directive used in this interaction.
Valid values: Dialog.ElicitSlot, Dialog.ConfirmSlot, Dialog.ConfirmIntent.

String

items.intent.confidence.bin

Confidence level of this interaction.
Valid values: HIGH, MEDIUM, LOW.

String

items.intent.name

Intent used in this interaction.

String

items.intent.slots.<slotname>.name

Slots returned to the skill in this interaction.

String

items.interactionType

Indicates whether the user invoked the skill and stated the intent in a single phrase (one shot), or the user invoked the skill first, and then stated the intent (modal).

String

items.locale

Locale in which this interaction occurred.
Valid values: All locales supported for custom skills, such as en-US.

String

items.publicationStatus

Publication stage of the skill when this interaction occurred.
Valid values: CERTIFICATION, DEVELOPMENT.

String

items.stage

Skill stage in which this interaction occurred.
Valid values: development, live.

String

items.utteranceText

Actual utterance text spoken by the user.

String

HTTP status codes

Status Description

200 OK

Response body contains a list of intent data.

400 Bad Request

Indicates that one or more properties in the request body are invalid.
The following example shows the response body with the error and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Object definitions

The Intent Request History API defines the following objects.

Locale values

The following table shows valid values for the locale property.

Locale code Language

ar-SA

Arabic (SA)

de-DE

German (DE)

en-AU

English (AU)

en-CA

English (CA)

en-GB

English (UK)

en-IN

English (IN)

en-US

English (US)

es-ES

Spanish (ES)

es-MX

Spanish (MX)

es-US

Spanish (US)

fr-CA

French (CA)

fr-FR

French (FR)

hi-IN

Hindi (IN)

it-IT

Italian (IT)

ja-JP

Japanese (JP)

pt-BR

Portuguese (BR)

Last updated: May 11, 2023