Metrics API

Get metrics

The Get Metrics API provides calculated metrics, insights, and advanced analytics reporting for skills usage.

API endpoint and header

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

The workflow is as follows:

  1. Make a request using SMAPI and the request below:
    GET /v1/skills/amzn1.ask.skill.001/metrics
  2. Enter the required and optional parameters, and then the Get Metrics API will return the list of data points that you requested.

Next Step: You can upload the metrics to an analytics tool such as spreadsheet, AWS QuickSight, AWS Redshift, or your own monitoring system.


GET /v1/skills/{skillId}/metrics?startTime={startTime}&endTime={endTime}&period={period}&metric={metric}&stage={stage}
&skillType={skillType}&intent={intent}&locale={locale}&maxResults={num}&nextToken={token} HTTP/1.1

Sample request

GET /v1/skills/amzn1.ask.skill.001/metrics?startTime=2018-11-01T10:45:00Z&endTime=2018-11-02T10:45:00Z&period=SINGLE&metric=uniqueCustomers&stage=live&skillType=custom&locale=en-US&maxResults=3&nextToken=token

Request parameters

Parameter Required Description Location Type
skillId Yes The unique identifier of a skill. Path String
startTime Yes The start time of the query. Query parameter String
endTime Yes The end time of the query. The maximum duration is 1 week. Query parameter String
period Yes The aggregation period that is used when retrieving the metric. The values are SINGLE, PT15M, PT1H, P1D. Query parameter Enum
metric Yes A distinct set of logic which predictably returns a set of data. For information on metric values, see Metric Skill Values. Query parameter Enum
stage Yes This parameter indicates the stage of the skill. The accepted values are: live or development. Query parameter Enum
skillType Yes The type of skill. Potential values are: custom, smartHome, or flashBriefing. Query parameter Enum
intent No The skill intent. Query parameter String
locale No The locale of the skill. Query parameter String
maxResults No The maximum number of results to display per page (100,000 is the maximum number of results). Query parameter Number
nextToken No Continuation token returned in response object of last get metrics report response. Query parameter String

Metric skill values by skill type:

Metric values for Custom skills:

  • uniqueCustomers
  • totalEnablements
  • totalUtterances
  • successfulUtterances
  • failedUtterances
  • totalSessions
  • successfulSessions
  • incompleteSessions
  • userEndedSessions
  • skillEndedSessions

Metric values for smartHome skills:

  • uniqueCustomers
  • totalEnablements
  • totalUtterances

Metric values for flashBriefing skills:

  • uniqueCustomers
  • totalEnablements
  • totalSessions


A successful request returns HTTP 200.

Response body structure

    "metric": "uniqueCustomers",
    "timestamps": [
    "values": [
    "nextToken": "string"

Response body fields

Field Description Type
GetMetricDataResponse GetMetricDataResponse is an object which contains metrics name, timestamps, values, and nextToken Object


An unsuccessful request returns one of the following errors:

Status code Description
HTTP 400 There is a validation error.
HTTP 401 The authorization token is invalid or expired or doesn't have access to the resource.
HTTP 403 The operation being requested isn't allowed.
HTTP 404 The resource you requested is not found.
HTTP 429 You have exceeded the permitted request limit. Throttling criteria includes total requests, per API, ClientId, and CustomerId.
HTTP 500 There is a internal server error.
HTTP 503 The service is unavailable.