Metrics REST API Reference v2
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
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.
POST
request instead of a GET
request.Request path and header example
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 |
---|---|---|---|---|
|
Path |
Identifies the skill. |
String |
Yes |
|
Header |
String |
Yes |
Request body example
The following example request queries the customer count and utterance count metrics for a skill.
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.
{
"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 |
---|---|---|---|
|
Starting timestamp for querying metrics in milliseconds. |
Long |
Yes |
|
Ending timestamp for querying metrics in milliseconds. |
Long |
Yes |
|
Maximum number of data points returned in the response body per query. |
Integer |
No |
|
Token from the previous response. |
String |
No |
|
Array of queries in the request. Each queried metric corresponds to a metric in the response. |
Array |
Yes |
|
Query ID. All query IDs must be unique. |
String |
Yes |
|
Brief, human-readable description of the metric associated with the specified query. |
String |
No |
|
Name of the requested metric. |
String |
Yes |
|
Namespace of the requested metric. |
String |
Yes |
|
Defines the field over which to aggregate the metrics across different categories. |
String |
No |
|
Period over which to aggregate the data. |
String |
Yes |
|
Statistic associated with the requested metric. |
String |
No |
|
Array of |
Array |
No |
|
Dimension name. |
String |
Yes |
|
Actual value of the specified dimension. |
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 |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Any |
|
|
|
|
|
|
|
|
|
|
|
|
|
Any user-specific string value |
|
|
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.
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 |
---|---|---|
|
(Optional) Wrapper for |
Object |
|
Collection of timestamps that support metric values for all metric queries sent to the request body. The |
Array of objects |
|
|
String |
|
|
String |
|
|
String |
|
|
String |
|
|
String |
|
Collection of metric values and timestamps corresponding to a single metric. If the query uses the |
Array of objects |
|
Series of metric values corresponding to the specified timestamps. |
Array of double |
|
Series of metric values corresponding to the specified timestamps. |
Array of double |
|
Object containing details about the |
Object |
|
Field name according to which to group the returned responses. |
String |
|
Field value. |
String |
HTTP status codes
Status | Description |
---|---|
|
Response body contains all the requested properties. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
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
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 |
---|---|---|---|---|
|
Query |
Namespace over which to query metrics. |
String |
Yes |
|
Query |
Maximum number of results to return in the response. |
Integer |
No |
|
Query |
Token from the previous response. |
String |
No |
|
Header |
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": "someToken.1"
},
"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 |
---|---|---|
|
(Optional) Wrapper for |
Object |
|
List of metrics that belong to the namespace specified in the request. |
Array of objects |
|
Name of the requested metric. |
String |
|
List of dimensions supported for the specified metric. |
Array of string |
|
List of |
Array of string |
|
List of statistics supported for the specified metric. |
Array of string |
HTTP status codes
Status | Description |
---|---|
|
Response body contains all the requested properties. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
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.
CUSTOMERS
metric has a different definition 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:
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:
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:
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
Alexa.Automation namespace
The following metrics are available under the Alexa.Automation
namespace:
AUTOMATION_ORIGINATION
AUTOMATION_EXECUTION
Related topics
Last updated: Aug 01, 2024