Metrics REST API Reference

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.

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.

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 the 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.Automation.Origination

OFFER_INITIATED_BY_SKILL, OFFER_SENT_TO_CUSTOMER, OFFER_ACCEPTED_BY_CUSTOMER, OFFER_NOT_ACCEPTED_BY_CUSTOMER

Alexa.Automation.Execution

AUTOMATION_EXECUTED

Alexa.Automation.TemplateId

Any TemplateId

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.

{
    "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 to group the returned responses.

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 to return in the response.
Default value: 100.

Integer

No

nextToken

Query

Token from the 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. The response doesn't include 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 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.

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

Alexa.Automation namespace

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

  • AUTOMATION_ORIGINATION
  • AUTOMATION_EXECUTION