Metrics API v1

You can use the Metric API to get calculated metrics, insights, and advanced analytics reporting for skill usage.

Get metrics

The Get Metrics API provides calculated metrics, insights, and advanced analytics reporting for skills usage. You can make a request using SMAPI and the GET /v1/skills/amzn1.ask.skill.001/metrics request, and supply the required and optional parameters, and then, the Get Metrics API will returns the list of data points that you requested. You can upload the metrics to an analytics tool, such as spreadsheet, AWS QuickSight, AWS Redshift, or your own monitoring system.

API endpoint and header

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.

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.

Request

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 one 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 that predictably returns a set of data. For information on metric values, see Skill metric values by skill type. Query parameter Enum
stage Yes This parameter shows 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 The continuation token returned in response to an object of the last get metrics report response. Query parameter String

Skill metric values by skill type:

For more details about available skill metrics by skill type, see About Skill Metrics.

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

Metric values for music, radio, and podcast skills:

  • uniqueCustomers
  • totalPlayQueuesDuration
  • playQueuesCount
  • successfulPlayQueueRate
  • averagePlayQueueLength

Response

A successful request returns HTTP 200.

Response body structure

{
    "metric": "uniqueCustomers",
    "timestamps": [
        "2018-11-01T10:45:00Z",
        "2018-11-01T10:45:00Z",
        "2018-11-01T10:45:00Z"
    ],
    "values": [
        10,
        20,
        30
    ],
    "nextToken": "string"
}

Response body fields

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

Errors

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 expired or not valid. Or, you don'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 an internal server error.
HTTP 503 The service is unavailable.
Was this page helpful?

Last updated: Sep 08, 2023