ListInsightsMetricData
Returns Insights metrics data for trails that have enabled Insights. The request must include the EventSource
,
EventName
, and InsightType
parameters.
If the InsightType
is set to ApiErrorRateInsight
, the request must also include the ErrorCode
parameter.
The following are the available time periods for ListInsightsMetricData
. Each cutoff is inclusive.
-
Data points with a period of 60 seconds (1-minute) are available for 15 days.
-
Data points with a period of 300 seconds (5-minute) are available for 63 days.
-
Data points with a period of 3600 seconds (1 hour) are available for 90 days.
Access to the ListInsightsMetricData
API operation is linked to the cloudtrail:LookupEvents
action. To use this operation,
you must have permissions to perform the cloudtrail:LookupEvents
action.
Request Syntax
{
"DataType": "string
",
"EndTime": number
,
"ErrorCode": "string
",
"EventName": "string
",
"EventSource": "string
",
"InsightType": "string
",
"MaxResults": number
,
"NextToken": "string
",
"Period": number
,
"StartTime": number
}
Request Parameters
For information about the parameters that are common to all actions, see Common Parameters.
The request accepts the following data in JSON format.
- DataType
-
Type of data points to return. Valid values are
NonZeroData
andFillWithZeros
. The default isNonZeroData
.Type: String
Valid Values:
FillWithZeros | NonZeroData
Required: No
- EndTime
-
Specifies, in UTC, the end time for time-series data. The value specified is exclusive; results include data points up to the specified time stamp.
The default is the time of request.
Type: Timestamp
Required: No
- ErrorCode
-
Conditionally required if the
InsightType
parameter is set toApiErrorRateInsight
.If returning metrics for the
ApiErrorRateInsight
Insights type, this is the error to retrieve data for. For example,AccessDenied
.Type: String
Length Constraints: Maximum length of 128.
Pattern:
^[\w\d\s_.,\-:\[\]]+$
Required: No
- EventName
-
The name of the event, typically the Amazon API on which unusual levels of activity were recorded.
Type: String
Length Constraints: Maximum length of 128.
Pattern:
^[A-Za-z0-9_]+$
Required: Yes
- EventSource
-
The Amazon service to which the request was made, such as
iam.amazonaws.com
ors3.amazonaws.com
.Type: String
Length Constraints: Maximum length of 256.
Pattern:
^[a-z0-9_-]+\.amazonaws\.com$
Required: Yes
- InsightType
-
The type of CloudTrail Insights event, which is either
ApiCallRateInsight
orApiErrorRateInsight
. TheApiCallRateInsight
Insights type analyzes write-only management API calls that are aggregated per minute against a baseline API call volume. TheApiErrorRateInsight
Insights type analyzes management API calls that result in error codes.Type: String
Valid Values:
ApiCallRateInsight | ApiErrorRateInsight
Required: Yes
- MaxResults
-
The maximum number of data points to return. Valid values are integers from 1 to 21600. The default value is 21600.
Type: Integer
Valid Range: Minimum value of 1. Maximum value of 21600.
Required: No
- NextToken
-
Returned if all datapoints can't be returned in a single call. For example, due to reaching
MaxResults
.Add this parameter to the request to continue retrieving results starting from the last evaluated point.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 5000.
Required: No
- Period
-
Granularity of data to retrieve, in seconds. Valid values are
60
,300
, and3600
. If you specify any other value, you will get an error. The default is 3600 seconds.Type: Integer
Valid Range: Minimum value of 60. Maximum value of 3600.
Required: No
- StartTime
-
Specifies, in UTC, the start time for time-series data. The value specified is inclusive; results include data points with the specified time stamp.
The default is 90 days before the time of request.
Type: Timestamp
Required: No
Response Syntax
{
"ErrorCode": "string",
"EventName": "string",
"EventSource": "string",
"InsightType": "string",
"NextToken": "string",
"Timestamps": [ number ],
"Values": [ number ]
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
- ErrorCode
-
Only returned if
InsightType
parameter was set toApiErrorRateInsight
.If returning metrics for the
ApiErrorRateInsight
Insights type, this is the error to retrieve data for. For example,AccessDenied
.Type: String
Length Constraints: Maximum length of 128.
Pattern:
^[\w\d\s_.,\-:\[\]]+$
- EventName
-
The name of the event, typically the Amazon API on which unusual levels of activity were recorded.
Type: String
Length Constraints: Maximum length of 128.
Pattern:
^[A-Za-z0-9_]+$
- EventSource
-
The Amazon service to which the request was made, such as
iam.amazonaws.com
ors3.amazonaws.com
.Type: String
Length Constraints: Maximum length of 256.
Pattern:
^[a-z0-9_-]+\.amazonaws\.com$
- InsightType
-
The type of CloudTrail Insights event, which is either
ApiCallRateInsight
orApiErrorRateInsight
. TheApiCallRateInsight
Insights type analyzes write-only management API calls that are aggregated per minute against a baseline API call volume. TheApiErrorRateInsight
Insights type analyzes management API calls that result in error codes.Type: String
Valid Values:
ApiCallRateInsight | ApiErrorRateInsight
- NextToken
-
Only returned if the full results could not be returned in a single query. You can set the
NextToken
parameter in the next request to this value to continue retrieval.Type: String
Length Constraints: Minimum length of 1. Maximum length of 5000.
- Timestamps
-
List of timestamps at intervals corresponding to the specified time period.
Type: Array of timestamps
- Values
-
List of values representing the API call rate or error rate at each timestamp. The number of values is equal to the number of timestamps.
Type: Array of doubles
Errors
For information about the errors that are common to all actions, see Common Errors.
- InvalidParameterException
-
The request includes a parameter that is not valid.
HTTP Status Code: 400
- OperationNotPermittedException
-
This exception is thrown when the requested operation is not permitted.
HTTP Status Code: 400
- UnsupportedOperationException
-
This exception is thrown when the requested operation is not supported.
HTTP Status Code: 400
Examples
Example
The following example shows how to retrieve API call rate metric data for the CloudTrail CreateTrail
API.
{ "EventSource": "cloudtrail.amazonaws.com", "EventName": "CreateTrail", "InsightType": "ApiCallRateInsight" }
Example
The following example shows how to retrieve API error rate metric data for receiving the error TrailNotFoundException
when calling the CloudTrail UpdateTrail
API.
{ "EventSource": "cloudtrail.amazonaws.com", "EventName": "UpdateTrail", "InsightType": "ApiErrorRateInsight", "ErrorCode": "TrailNotFoundException" }
See Also
For more information about using this API in one of the language-specific Amazon SDKs, see the following: