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 developer console. See Review the Intent History for a Custom Skill.

 

Request

GET /v1/skills/{skillId}/history/intentRequests

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.

GET  /v1/skills/{skillId}/history/intentRequests?
     nextToken=VWB111111111
     &maxResults=5
     &sortField=intent.confidence.bin	 
     &sortDirection=desc
     &locale=en-US&locale=en-GB
     &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%20is
     &intent.name=AnswerIntent
     &interactionType=MODAL

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.

HTTP/1.1 200 OK
Content-Type: application/json+hal
{
  "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
nextTokenUse nextToken to load next set of results.
totalCountTotal number of results that matched the query. totalCount ≥ 0
skillIdThe skill for which the intent request history data is returned.
startIndexThe position of the token in the current result set.
isTruncatedThis property is true when all the results matching the search request haven't been returned, and false otherwise
itemsCollection 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.nameIntent used in this interaction.
item.localelocale 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.nameSlots returned to the skill.
item.stageThe 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.utteranceTextThe 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:

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
HTTP/1.1 500 Internal Server Error
HTTP/1.1 503 Service Unavailable