Metrics API

You can use the Metrics 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.

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 the access token retrieved from Login with Amazon (LWA).

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

Gets the metrics for the Alexa skill with the specified skillId.

Request

To get the metrics for a skill, you make a POST request to the /v2/skills/{skillId}/metrics resource. You can query up to five metrics in a single request.

Request header example

Copied to clipboard.

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

Request header parameters

Parameter Description Type Required

skillId

ID of the skill whose metrics to query.

String

Yes

Content-Type

Content type of the request

String

Yes

access token

LWA token

String

Yes

Request body example

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

Copied to clipboard.

{
    "startTime": 1625097600000,
    "endTime": 1627689600000,
    "skillId": "amzn1.ask.skill.1",
    "metricQueries": [
      {
        "id": "m1",
        "label": "Count of customers",
        "stat": "count",
        "name": "CUSTOMERS",
        "groupBy": "intent",
        "metricNamespace": "Alexa.Custom",
        "aggregationPeriod": "BY_WEEK",
        "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 parameters

Parameter Description Type Required

startTime

Starting timestamp for querying metrics.

Long

Yes

endTime

Ending timestamp for querying metrics.

Long

Yes

skillId

ID of the skill whose metrics to query.

String

Yes

maxResultsPerQuery

Maximum number of data points returned in the response body per query. Default value is 100.

Integer

No

nextToken

Token returned if the response is paginated.

String

No

metricQueries

Array of queries in the request. Each queried metric corresponds to a metric in the response.

Array

Yes

metricQueries[i].id

Query ID. All query IDs must be unique.

String

Yes

metricQueries[i].label

Brief, human-readable description of the metric associated with the specified query.

String

No

metricQueries[i].stat

Statistic associated with the requested metric. Valid values: count, p99, p90, p50, avg

String

No

metricQueries[i].name

Name of the requested metric. For a list of valid metric names, see Namespaces and metrics.

String

Yes

metricQueries[i].metricNamespace

Namespace associated with the requested metric. For a list of valid namespaces, see Namespaces and metrics.

String

Yes

metricQueries[i].aggregationPeriod

Period over which to aggregate the data. Valid values: BY_15, BY_DAY, BY_HOUR, BY_WEEK, SINGLE

String

Yes

metricQueries[i].groupBy

Parameter that lets you find the distribution of a metric across different categories. The groupBy options differ from metric to 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[i].dimensions

Array of Dimensions objects. For valid values, see dimensions object. Dimensions are optional.

Array

No

metricQueries[i].dimensions.name

A dimension name. For valid values, see dimensions object.

String

No

metricQueries[i].dimensions.value

Actual value of the specified dimension. For valid values, see dimensions object.

String

No

dimensions object

You use the dimensions objects to declare specific attribute values for getting metric data. The following table shows the allowed values of dimensions.

Dimension Allowed 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, along with the requested metrics.

Response body example

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

{
    "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 parameters

Parameter Description Type

paginationContext

Wrapper for nextToken, which is returned if 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[i].id

The id field sent in the corresponding request query.

String

results[i].label

The label field sent in the corresponding request query.

String

results[i].metricNamespace

The metricNamespace field sent in the corresponding request query.

String

results[i].name

The name of the metric sent in the corresponding request query.

String

results[i].stat

The stat field sent in the corresponding request query.

String

results[i].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[i].data[i].timestamps

Series of metric values corresponding to the specified timestamps.

Array of double

results[i].data[i].values

Series of metric values corresponding to the specified timestamps.

Array of double

results[i].data[i].groupedBy

Object containing details about the groupBy response.

Object

results[i].data[i].groupedByField

The field name according to which returned responses are categorized.

Object

results[i].data[i].groupedByValue

The groupBy field value.

Object

HTTP status codes

Status Description

200 Success

Response body contains all the requested properties.

400 Bad Request

Bad request due to invalid or missing data.

401 Unauthorized

Authorization token invalid or expired. Client lacks the necessary authentication to access protected server resources.

403 Forbidden

Client's identity is known to the server, but client is not authorized to access the protected resources.

404 Not Found

Requested resource not found.

429 Too Many Requests

User has exceeded the permitted rate limit (specified number of requests per unit of time).

500 Internal Server Error

Server has encountered an error.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

List metrics

Gets the metrics available 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 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 header parameters

Parameter Description Type Required

Content-Type

Content type of the request

String

Yes

Authorization

LWA token

String

Yes

namespace

Namespace over which to query metrics. For a list of valid namespaces, see Namespaces and metrics.

String

Yes

maxResults

Maximum number of results returned. The default value is 100.

Integer

No

nextToken

Pagination token received in the previous iteration if iterating over a paginated response.

String

No

Request body parameters

The request body is empty.

Response

A successful response returns HTTP 200, along with metrics and details from the specified namespace.

Response body example without pagination

The following example shows a response without pagination. (There isn't a paginationContext object.)

{
    "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 parameters

Parameter Description Type

paginationContext

Wrapper for nextToken, which is returned in paginated responses.

Object

metrics

Array of metrics that belong to the namespace specified in the request.

Array

metrics[i].name

Name of the requested metric

String

metrics[i].supportedDimensions

List of dimensions supported in the request for the specified metric.

Array

metrics[i].supportedGroupByOptions

List of groupBy options supported in the request for the specified metric.

Array

metrics[i].supportedStats

List of statistics supported in the request for the specified metric.

Array

HTTP status codes

Status Description

200 Success

Response body contains all the requested properties.

400 Bad Request

Bad request due to invalid or missing data.

401 Unauthorized

Authorization token invalid or expired. Client lacks the necessary authentication to access protected server resources.

403 Forbidden

Client's identity is known to the server, but client is not authorized to access the protected resources.

404 Not Found

Requested resource not found.

429 Too Many Requests

User has exceeded the permitted rate limit (specified number of requests per unit of time).

500 Internal Server Error

Server has encountered an error.

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.

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:

  • PREDICTED_UTTERANCES
  • EVALUATED_UTTERANCES
  • FUD_FAILURE_PERCENTILES
  • FAILURE_PREDICTION_OFFSET

Alexa.SkillQuality namespace

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

  • 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:

  • TRAFFIC
  • NAME_FREE_INVOCATIONS
  • FUD_NAME_FREE_INVOCATIONS
  • DIRECT_INVOCATIONS
  • ONE_SHOT_INVOCATIONS
  • ROUTINES_INVOCATIONS
  • QUICK_LINKS_INVOCATIONS
  • SKILL_CONNECTION_INVOCATIONS