Metrics REST API Reference

Note: Watch the replay of Alexa Live ‘22 on demand. Catch the latest on ambient intelligence, smart home, and AI.

Important: The Metrics REST API is in beta and is subject to change at any time without notice.

You can use the Metrics REST API to get advanced analytics on skill usage. For a list of available metrics, see Namespaces and metrics. To query by skill ID, use Get metrics. To query by namespace, use List metrics.

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

API endpoint

The endpoint of the Metrics API is https://api.amazonalexa.com.

Authentication

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

Operations

The Metrics API includes the following operations.

Operation	HTTP method and URI
Get metrics	`POST /v2/skills/{skillId}/metrics`
List metrics	`GET /v2/skills/metrics?metricNamespace={namespace}&maxResults={maxResults}&nextToken={nextToken}`

Get metrics

Get the metrics for the specified Alexa skill. You can query up to five metrics in a single request.

Request

To get the metrics for a skill, you make a POST request to the /v2/skills/{skillId}/metrics resource.

Note: To specify multiple filter parameters, you make a POST request instead of a GET request.

Request path and header example

Copied to clipboard.

POST /v2/skills/{skillId}/metrics
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`skillId`	Path	Identifies the skill. Valid values: 1 – 255 characters	String	Yes
`access token`	Header	LWA token	String	Yes

Request body example

The following example request queries the customer count and utterance count metrics for a skill.

Note: The query with id = m1 uses the metricQueries[].groupBy parameter to find the distribution of a metric across different categories. The query with id = m2 doesn't use the metricQueries[].groupBy parameter.

Copied to clipboard.

{
    "startTime": 1625097600000,
    "endTime": 1627689600000,
    "metricQueries": [
      {
        "id": "m1",
        "label": "Count of customers",
        "name": "CUSTOMERS",
        "metricNamespace": "Alexa.Custom",
        "groupBy": "intent",
        "aggregationPeriod": "BY_WEEK",
        "stat": "count",
        "dimensions": [
          {
            "name": "Alexa.Stage",
            "value": "development"
          },
          {
            "name": "Alexa.Locale",
            "value": "en-US"
          }
        ]
      },
      {
        "id": "m2",
        "name": "UTTERANCES",
        "metricNamespace": "Alexa.Custom",
        "aggregationPeriod": "BY_WEEK",
        "dimensions": [
          {
            "name": "Alexa.Stage",
            "value": "development"
          },
          {
            "name": "Alexa.Locale",
            "value": "en-US"
          }
        ]
      }
    ]
}

Request body properties

Property	Description	Type	Required
`startTime`	Starting timestamp for querying metrics in milliseconds.	Long	Yes
`endTime`	Ending timestamp for querying metrics in milliseconds.	Long	Yes
`maxResultsPerQuery`	Maximum number of data points returned in the response body per query. Default value: 100.	Integer	No
`nextToken`	Token from previous response. Include if iterating over a paginated response.	String	No
`metricQueries`	Array of queries in the request. Each queried metric corresponds to a metric in the response.	Array	Yes
`metricQueries[].id`	Query ID. All query IDs must be unique.	String	Yes
`metricQueries[].label`	Brief, human-readable description of the metric associated with the specified query.	String	No
`metricQueries[].name`	Name of the requested metric. For a list of valid metric names, see Namespaces and metrics.	String	Yes
`metricQueries[].metricNamespace`	Namespace of the requested metric. For a list of valid namespaces, see Namespaces and metrics.	String	Yes
`metricQueries[].groupBy`	Defines the field over which to aggregate the metrics across different categories. The `groupBy` options differ from metric to metric. Use the `List metrics` API to find the options for a specific namespace and metric. For example, you can group the `UTTERANCES` metric by intent. The result might show `SpeakIntent` with a metric value series of `[0,1,0]`, `LaughIntent` with `[3,2,1]`, and `ShoutIntent` with `[5,0,0]`, and so on.	String	No
`metricQueries[].aggregationPeriod`	Period over which to aggregate the data. Valid values: `BY_15`, `BY_DAY`, `BY_HOUR`, `BY_WEEK`, `SINGLE`.	String	Yes
`metricQueries[].stat`	Statistic associated with the requested metric. Use the `List metrics` API to find the options for a specific namespace and metric. Valid values: `count`, `p99`, `p90`, `p50`, `avg`.	String	No
`metricQueries[].dimensions`	Array of `Dimensions` objects. Use the `List metrics` API to find the options for a specific namespace and metric.	Array	No
`metricQueries[].dimensions[].name`	Dimension name. For valid values, see `Dimensions` object values.	String	Yes
`metricQueries[].dimensions[].value`	Actual value of the specified dimension. For valid values, see `Dimensions` object.	String	Yes

Dimensions object values

You use the Dimensions objects to declare specific attribute values for the Get metrics request. The following table shows the allowed values of Dimensions name and values.

Dimension name	Dimension values
`Alexa.Stage`	`live`, `development`
`Alexa.Locale`	`de-DE`, `en-AU`, `en-CA`, `en-GB`, `en-IN`, `en-US`, `es-ES`, `es-MX`, `es-US`, `fr-CA`, `fr-FR`, `hi-IN`, `it-IT`, `ja-JP`, `pt-BR`
`Alexa.Marketplace`	`USAmazon`, `EUAmazon`
`Alexa.SluConfidence`	`HIGH`, `MEDIUM` (default), `LOW`
`Alexa.AccountActivationEvents.Status`	`INITIATED` (default), `COMPLETED`
`Alexa.SkillInvocations.TrafficType`	`NEW`, `RETURNING`
`Alexa.EstimatedTurnError.InvocationType`	`DIRECT_INVOCATIONS`, `NAME_FREE_INVOCATIONS`, `ONE_SHOT_INVOCATIONS`, `ROUTINES_INVOCATIONS`, `QUICK_LINKS_INVOCATIONS`, `SKILL_CONNECTION_INVOCATIONS`
`Alexa.EstimatedTurnError.PredictionOutcome`	`SUCCESS`, `FAILURE`
`Alexa.EstimatedTurnError.UserType`	`NEW`, `RETURNING`
`Alexa.SkillQuality.InvocationType`	`DIRECT_INVOCATIONS`, `NAME_FREE_INVOCATIONS`, `ONE_SHOT_INVOCATIONS`, `ROUTINES_INVOCATIONS`, `QUICK_LINKS_INVOCATIONS`, `SKILL_CONNECTION_INVOCATIONS`
`Alexa.SkillQuality.UserType`	`NEW`, `RETURNING`
`Intent`	Any user-specific string value
`Country`	`AU`, `CA`, `DE`, `ES`, `FR`, `GB`, `IN`, `IT`, `JP`, `MX`, `US`

Response

A successful response returns HTTP 200 OK, along with the requested metrics.

Response body example

The following example shows the response for the query in the Request body example.

Note: The query results for id = m1 are grouped by category because the query used the metricQueries[].groupBy parameter.

{
    "results": [
        {
            "data": [
                {
                    "groupedBy": {
                        "groupedByField": "intent",
                        "groupedByValue": "WatchTVIntent"
                    },
                    "timestamps": [
                        162509760000,
                        1635206400000
                    ],
                    "values": [
                        3.0,
                        4.0
                    ]
                },
                {
                    "groupedBy": {
                        "groupedByField": "intent",
                        "groupedByValue": "LaughIntent"
                    },
                    "timestamps": [
                        162509760000,
                        1635206400000
                    ],
                    "values": [
                        1.0,
                        2.0
                    ]
                },
                {
                    "groupedBy": {
                        "groupedByField": "intent",
                        "groupedByValue": "SleepIntent"
                    },
                    "timestamps": [
                       162509760000,
                       1635206400000
                    ],
                    "values": [
                        0.0,
                        2.0
                    ]
                }
            ],
            "id": "m1",
            "label": "Count of customers",
            "metricNamespace": "Alexa.Custom",
            "name": "CUSTOMERS",
            "stat": "count"
        },
        {
            "data": [
                {
                    "timestamps": [
                       162509700000,
                       1635206400000
                    ],
                    "values": [
                        1.0,
                        0.0
                    ]
                }
            ],
            "id": "m2",
            "metricNamespace": "Alexa.Custom",
            "name": "UTTERANCES"
        }
    ]
}

Response body properties

Property	Description	Type
`paginationContext`	(Optional) Wrapper for `nextToken`. Included when the response is paginated.	Object
`results`	Collection of timestamps that support metric values for all metric queries sent to the request body. The `id` field of each object matches the corresponding `id` field in request body.	Array of objects
`results[].id`	`id` field sent in the corresponding request query.	String
`results[].label`	`label` field sent in the corresponding request query.	String
`results[].metricNamespace`	`metricNamespace` field sent in the corresponding request query.	String
`results[].name`	`name` of the metric sent in the corresponding request query.	String
`results[].stat`	`stat` field sent in the corresponding request query.	String
`results[].data`	Collection of metric values and timestamps corresponding to a single metric. If the query uses the `groupBy` parameter, the query returns multiple arrays. If the query doesn't use the `groupBy` parameter, the query returns a single array of metric values and timestamps.	Array of objects
`results[].data[].timestamps`	Series of metric values corresponding to the specified timestamps.	Array of double
`results[].data[].values`	Series of metric values corresponding to the specified timestamps.	Array of double
`results[].data[].groupedBy`	Object containing details about the `groupBy` response.	Object
`results[].data[].groupedBy.groupedByField`	Field name according to which returned responses are categorized.	String
`results[].data[].groupedBy.groupedByValue`	Field value.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains all the requested properties.
`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.

List metrics

Gets all available metrics within a given namespace.

Request

To get the metrics within a given namespace, you make a GET request to the /v2/skills/metrics resource.

Request path and header example

Copied to clipboard.

GET /v2/skills/metrics?metricNamespace={namespace}&maxResults={maxResults}&nextToken={nextToken}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`namespace`	Query	Namespace over which to query metrics. For a list of valid namespaces, see Namespaces and metrics.	String	Yes
`maxResults`	Query	Maximum number of results returned. Default value: 100.	Integer	No
`nextToken`	Query	Token from previous response. Include if iterating over a paginated response.	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 metrics and details from the specified namespace.

Response body example without pagination

The following example shows a response without pagination. No paginationContext object is included.

{
    "metrics": [
        {
            "name": "CUSTOMERS",
            "supportedDimensions": [
                "Alexa.Locale",
                "Alexa.Stage"
            ],
            "supportedGroupByOptions": [
                "intent"
            ],
            "supportedStats": [
                "count"
            ]
        },
        {
            "name": "UTTERANCES",
            "supportedDimensions": [
                "Alexa.Locale",
                "Alexa.Stage"
            ],
            "supportedGroupByOptions": [
                "intent"
            ],
            "supportedStats": [
                "count"
            ]
        },
        {
            "name": "UTTERANCES_PER_CUSTOMER",
            "supportedDimensions": [
                "Alexa.Locale",
                "Alexa.Stage"
            ]
        }
    ]
}

Response body example with pagination

The following example shows a paginated response.

{
    "paginationContext": {
        "nextToken": "abcd1234"
    },
    "metrics": [
        {
            "name": "UTTERANCES",
            "supportedDimensions": [
                "Alexa.Locale",
                "Alexa.Stage"
            ],
            "supportedGroupByOptions": [
                "intent"
            ],
            "supportedStats": [
                "count"
            ]
        },
        {
            "name": "UTTERANCES_PER_CUSTOMER",
            "supportedDimensions": [
                "Alexa.Locale",
                "Alexa.Stage"
            ]
        }
    ]
}

Response body properties

Property	Description	Type
`paginationContext`	(Optional) Wrapper for `nextToken`. Included when the response is paginated.	Object
`metrics`	List of metrics that belong to the namespace specified in the request.	Array of objects
`metrics[].name`	Name of the requested metric.	String
`metrics[].supportedDimensions`	List of dimensions supported for the specified metric. For details, see Dimensions object.	Array of string
`metrics[].supportedGroupByOptions`	List of `groupBy` options supported for the specified metric.	Array of string
`metrics[].supportedStats`	List of statistics supported for the specified metric.	Array of string

HTTP status codes

Status	Description
`200 OK`	Response body contains all the requested properties.
`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.

Namespaces and metrics

Namespaces group skill metrics into categories. Some namespaces are topics (for example, Alexa.Music), and some namespaces relate to functionality (for example, Alexa.SkillInvocations). The following sections list the available metrics under each namespace.

Important: Queries for namespace metrics are meaningful only in the context of their respective namespaces. The CUSTOMERS metric, for example, is defined differently and returns different data in Alexa.SmartHome than it does in Alexa.Music or Alexa.Custom. Know the context of a metric before you use it in an API call.

Alexa.Custom namespace

The following metrics are available under the Alexa.Custom namespace:

CUSTOMERS
SUCCESSFUL_SESSIONS
ACTIVE_SESSIONS
ACTIVE_SESSIONS_PER_CUSTOMER
ENDED_SESSIONS
USER_ENDED_SESSIONS
SKILL_ENDED_SESSIONS
DIFF_ACTIVE_SESSIONS_ENDED_SESSIONS
UTTERANCES
SUCCESSFUL_UTTERANCES
UTTERANCES_PER_CUSTOMER
UTTERANCES_PER_ACTIVE_SESSION
FAILED_UTTERANCES
FAILED_UTTERANCES_SESSION
USER_RESPONDED
USER_DID_NOT_RESPOND
INTENT_CLASSIFICATION
SKILL_LATENCY

Alexa.SmartHome namespace

The following metrics are available under the Alexa.SmartHome namespace:

CUSTOMERS
UTTERANCES
UTTERANCES_PER_CUSTOMER

Alexa.AccountActivationEvents namespace

The following metrics are available under the Alexa.AccountActivationEvents namespace:

USERS
EVENTS
ALEXA_APP_USERS
ALEXA_APP_EVENTS
ALEXA_APP_INITIATIONS_PER_USER
APP_TO_APP_USERS
APP_TO_APP_EVENTS
APP_TO_APP_COMPLETION_RATE
APP_TO_APP_INITIATIONS_PER_USER
TOTAL_COMPLETION_RATE

Alexa.Music namespace

The following metrics are available under the Alexa.Music namespace:

CUSTOMERS
FRICTION_RATE
TOP_MEDIA_CONTENT
SUCCESSFUL_PLAYBACK_RATE
PLAY_QUEUES
PLAY_QUEUE_DURATION
AVERAGE_PLAY_QUEUE_DURATION
AVERAGE_PLAY_QUEUES_PER_CUSTOMER
AVERAGE_PLAY_QUEUE_DURATION_PER_CUSTOMER

Alexa.SkillEnablementEvents namespace

The following metrics are available under the Alexa.SkillEnablementEvents namespace:

USERS

Alexa.EstimatedTurnError namespace

The following metrics are available under the Alexa.EstimatedTurnError namespace:

Note: In the metric names, FUD stands for frequent utterances database.

PREDICTED_UTTERANCES
EVALUATED_UTTERANCES
FUD_FAILURE_PERCENTILES
FAILURE_PREDICTION_OFFSET

Alexa.SkillQuality namespace

The following metrics are available under the Alexa.SkillQuality namespace:

Note: In the metric names, FUD stands for frequent utterances database.

UTTERANCES
DEFECTIVE_UTTERANCES
EVALUATED_UTTERANCES
DEFECTIVE_BARGE_INS
DEFECTIVE_BARGE_IN_RATE
FUD_DEFECTIVE_BARGE_INS
DEFECTIVE_REPHRASE
DEFECTIVE_TERMINATION
FUD_DEFECTS
FUD_DEFECTIVE_TERMINATION
UNHANDLED_REQUEST
FRICTION_RATE_BASELINE_OFFSET
DEFECTIVE_TERMINATION_RATE
UNHANDLED_REQUEST_RATE

Alexa.SkillInvocations namespace

The following metrics are available under the Alexa.SkillInvocations namespace:

Note: In the metric names, FUD stands for frequent utterances database.

TRAFFIC
NAME_FREE_INVOCATIONS
FUD_NAME_FREE_INVOCATIONS
DIRECT_INVOCATIONS
ONE_SHOT_INVOCATIONS
ROUTINES_INVOCATIONS
QUICK_LINKS_INVOCATIONS
SKILL_CONNECTION_INVOCATIONS

Metrics REST API Reference

API endpoint

Authentication

Operations

Get metrics

Request

Request path and header example

Request path and header parameters

Request body example

Request body properties

Dimensions object values

Response

Response body example

Response body properties

HTTP status codes

List metrics

Request

Request path and header example

Request path and header parameters

Request body example

Request body properties

Response

Response body example without pagination

Response body example with pagination

Response body properties

HTTP status codes

Namespaces and metrics

Alexa.Custom namespace

Alexa.SmartHome namespace

Alexa.AccountActivationEvents namespace

Alexa.Music namespace

Alexa.SkillEnablementEvents namespace

Alexa.EstimatedTurnError namespace

Alexa.SkillQuality namespace

Alexa.SkillInvocations namespace

Related topics