Intent Request History

The Intent Request History API provides skill developers with the aggregated and anonymized transcriptions of user speech data and intent request details for their skills, on a per-skill basis. A skill must have at least 10 unique users per locale in a day, in order for data to be available for that locale for that day. If some locales meet the threshold and other locales do not, data is returned only for those locales that meet the threshold.

This API supports the following features:

• Text search and sort functionality for the results
• Paginated results
• Data that is updated daily, and based on customer interactions over the past 30 days

The data provided is a subset of utterances sent to your skill, filtered to include only frequent utterances. This means that there might not be any utterances returned, even if the daily user threshold has been met.

The API's endpoint is https://api.amazonalexa.com. Each API request must have an Authorization header whose value should be the access token retrieved from Login with Amazon.

All SMAPI v1 APIs will throw the following error responses if appropriate: HTTP/1.1 429 TooManyRequestsException if a request is throttled, and HTTP/1.1 503 if a service is unavailable.

For the command line interface version of this command, see Alexa Skills Kit Command Line Interface (ASK CLI) Command Reference.

You can also view intent history in the Alexa developer console. For details, see Review the Intent History for a Custom Skill.

• Request
  • Parameters
  • Sample Request
• Response
  • Response Attributes
  • Exceptions

 

Request

Parameters

Property	Required	Parameter Type	Description
skillId	Yes	Path	The skillId for which utterance data is returned. Valid value: A valid skill id
nextToken	No	Query parameter	nextToken is used to sequentially page through the result items. Use nextToken along with the maxResults parameter to specify how many results should be loaded in the page. To load the first page this property can be set to null. It expires in 60 minutes. This token is bound to the set of filters and the skillId that were used to obtain it, and will be ignored if used with other parameters: the first page of results for the new search parameters will be returned. Default value: null
sortField	No	Query parameter	Result items are sorted according to the value of the field specified in this attribute. Sorting order is defined in the separate attribute sortDirection. This field is not case-sensitive. Valid values: dialogAct.name, locale, intent.confidence.bin, stage, publicationStatus, intent.name, interactionType, or utteranceText
sortDirection	No	Query parameter	The order in which sorting would be applied. By default, the sorting order is descending. This field is not case-sensitive. Default value: desc Valid values: asc (for ascending) or desc (for descending)
maxResults	No	Query parameter	Maximum number of result items (at-most and not at-least) that will be returned in the response. By default, this number is set to 10. maxResults has an upper limit of 250. Default value: 10 Valid values: Positive integers between 1 and 250 (inclusive)
dialogAct.name	No	Query parameter	dialogAct.name filter matches the result items where the dialogAct.name value matches one of the values in this filter. This filter can have multiple values and is not case-sensitive. These values arise in the context of a multi-turn conversation. For more information about the Dialog directive and multi-turn conversations, see Dialog Interface Reference. Default values: null Valid values: Dialog.ElicitSlot, Dialog.ConfirmSlot, or Dialog.ConfirmIntent
locale	No	Query parameter	locale filter matches the result items where the locale value matches one of the values in this filter. This filter can have multiple values and is not case-sensitive. Default value: null Valid values: All currently supported locales. Example: en-US
intent.confidence.bin	No	Query parameter	intent.confidence.bin filter matches the result items where the intent.confidence.bin value matches one of the values in this filter. Note that at runtime, skills do not receive intents with LOW confidence. This filter can have multiple values and is not case-sensitive. All intent requests are automatically divided into HIGH, MEDIUM, and LOW confidence bins, depending on how confident the identification is. Default value: null Valid values: HIGH, MEDIUM, OR LOW
stage	No	Query parameter	stage filter matches the result items where the stage value matches one of the values in this filter. This filter can have multiple values and is not case-sensitive. This attribute is used to separate intent requests for the live version of the skill from development versions of the skill. Default value: null Valid values: live or development
publicationStatus	No	Query parameter	publicationStatus filter matches the result items where the publicationStatus value matches one of the values in this filter. This filter can have multiple values and is not case-sensitive. Default value: null Valid values: CERTIFICATION or DEVELOPMENT
utteranceText	No	Query parameter	utteranceText filter matches the result items based on a full-text search of utteranceText values. This filter can have multiple values and is not case-sensitive. Default value: null Valid values: Any string
intent.name	No	Query parameter	intent.name filter matches the result items where the intent.name values matches one of the values in this filter. This filter can have multiple values and is not case-sensitive. Default value: null Valid values: Any string without white spaces
intent.slot.name	No	Query parameter	This filter matches the results where the intent.slots.slot.name matches one or more of the values in this filter. This filter can have multiple values and is not case-sensitive. Default value: null Valid values: Any string without white spaces
interactionType	No	Query parameter	This filter matches the results where the interactionType value matches the value(s) in this filter. Indicates if the utterance was executed as a ONE_SHOT interaction or MODAL interaction. ONE_SHOT: The user invokes the skill and states their intent in a single phrase. MODAL: The user first invokes the skill and then states their intent. This filter can have multiple values. Default value: null Valid values: ONE_SHOT or MODAL

Sample Request

This sample request to GET the intent requests history demonstrates how requests to the Intent Request History API can be filtered by various combinations of attributes.

In this case, the sort results are listed in a descending order and sorted by the intent.confidence.bin field, for results in the en-US or en-GB locale, with intent.confidence.bin values of HIGH or MEDIUM, with a stage of development and a publicationStatus of CERTIFICATION. Additional filtering is done to narrow the results by dialog, slot name, the text of the utterance, and more.

The sample request has been given line breaks here for readability, but should be concatenated without line breaks.

Other values for stage and publicationStatus can be used to obtain different results. For example, setting stage to live will give you the intent request history for the live version of the skill.

Response

Here is a sample response.

{
  "body": {
    "_links": {
      "self": {
        "href": "v1/skills/{skillId}/history/intentRequests?nextToken=VWB111111111&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/{skillId}/history/intentRequests?nextToken=VXjbbbbbbbbb&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"
      }
    },
    "nextToken": "VXjbbbbbbbbb",
    "totalCount": 15,
    "skillId": "amzn1.ask.skill.12345678-1234-1234-123456789123",
    "startIndex": 0,
    "isTruncated": true,
    "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 Attributes

Field	Description
nextToken	Use nextToken to load next set of results.
totalCount	Total number of results that matched the query. totalCount ≥ 0
skillId	The skill for which the intent request history data is returned.
startIndex	The position of the token in the current result set.
isTruncated	This property is true when all the results matching the search request haven't been returned, and false otherwise
items	Collection of utterance data
item.intent.confidence.bin	Confidence level on this interaction or item. One of: HIGH MEDIUM LOW
item.dialogAct.name	The dialogAct used in this interaction. One of: Dialog.ElicitSlot Dialog.ConfirmSlot Dialog.ConfirmIntent
item.intent.name	Intent used in this interaction.
item.locale	locale in which this interaction occurred. One of: en-US, en-GB, en-IN, en-CA, en-AU, de-DE, fr-FR, or ja-JP.
item.intent.slots.name	Slots returned to the skill.
item.stage	The skill stage in which this interaction occurred. Valid values: live or development
item.publicationStatus	The skill state in which this interaction occurred. One of: CERTIFICATION DEVELOPMENT
item.utteranceText	The actual customer interaction with the skill.
item.interactionType	Indicates if the utterance was executed as a ONE_SHOT interaction or MODAL interaction. One of: ONE_SHOT: The user invokes the skill and states their intent in a single phrase. MODAL: The user first invokes the skill and then states their intent.

Exceptions

The list of response exceptions are as follows: