Skip to content

CloudTrail  >  Operations  >  list_insights_metric_data

list_insights_metric_data

Operation

list_insights_metric_data async 

list_insights_metric_data(input: ListInsightsMetricDataInput, plugins: list[Plugin] | None = None) -> ListInsightsMetricDataOutput

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.

To use ListInsightsMetricData operation, you must have the following permissions:

  • If ListInsightsMetricData is invoked with TrailName parameter, access to the ListInsightsMetricData API operation is linked to the cloudtrail:LookupEvents action and cloudtrail:ListInsightsData. To use this operation, you must have permissions to perform the cloudtrail:LookupEvents and cloudtrail:ListInsightsData action on the specific trail.

  • If ListInsightsMetricData is invoked without TrailName parameter, access to the ListInsightsMetricData API operation is linked to the cloudtrail:LookupEvents action only. To use this operation, you must have permissions to perform the cloudtrail:LookupEvents action.

Parameters:

Name Type Description Default
input ListInsightsMetricDataInput

An instance of ListInsightsMetricDataInput.

 required
plugins list[Plugin] | None

A list of callables that modify the configuration dynamically. Changes made by these plugins only apply for the duration of the operation execution and will not affect any other operation invocations.

 None

Returns:

Type Description
ListInsightsMetricDataOutput

An instance of ListInsightsMetricDataOutput.

Input

ListInsightsMetricDataInput dataclass

Dataclass for ListInsightsMetricDataInput structure.

Attributes

data_type class-attribute instance-attribute 
data_type: InsightsMetricDataType | None = None

Type of data points to return. Valid values are NonZeroData and FillWithZeros. The default is NonZeroData.

end_time class-attribute instance-attribute 
end_time: datetime | None = None

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.

error_code class-attribute instance-attribute 
error_code: str | None = None

Conditionally required if the InsightType parameter is set to ApiErrorRateInsight.

If returning metrics for the ApiErrorRateInsight Insights type, this is the error to retrieve data for. For example, AccessDenied.

event_name class-attribute instance-attribute 
event_name: str | None = None

The name of the event, typically the Amazon Web Services API on which unusual levels of activity were recorded.

event_source class-attribute instance-attribute 
event_source: str | None = None

The Amazon Web Services service to which the request was made, such as iam.amazonaws.com or s3.amazonaws.com.

insight_type class-attribute instance-attribute 
insight_type: InsightType | None = None

The type of CloudTrail Insights event, which is either ApiCallRateInsight or ApiErrorRateInsight. The ApiCallRateInsight Insights type analyzes write-only management API calls that are aggregated per minute against a baseline API call volume. The ApiErrorRateInsight Insights type analyzes management API calls that result in error codes.

max_results class-attribute instance-attribute 
max_results: int | None = None

The maximum number of data points to return. Valid values are integers from 1 to 21600. The default value is 21600.

next_token class-attribute instance-attribute 
next_token: str | None = None

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.

period class-attribute instance-attribute 
period: int | None = None

Granularity of data to retrieve, in seconds. Valid values are 60, 300, and 3600. If you specify any other value, you will get an error. The default is 3600 seconds.

start_time class-attribute instance-attribute 
start_time: datetime | None = None

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.

trail_name class-attribute instance-attribute 
trail_name: str | None = None

The Amazon Resource Name(ARN) or name of the trail for which you want to retrieve Insights metrics data. This parameter should only be provided to fetch Insights metrics data generated on trails logging data events. This parameter is not required for Insights metric data generated on trails logging management events.

Output

ListInsightsMetricDataOutput dataclass

Dataclass for ListInsightsMetricDataOutput structure.

Attributes

error_code class-attribute instance-attribute 
error_code: str | None = None

Only returned if InsightType parameter was set to ApiErrorRateInsight.

If returning metrics for the ApiErrorRateInsight Insights type, this is the error to retrieve data for. For example, AccessDenied.

event_name class-attribute instance-attribute 
event_name: str | None = None

The name of the event, typically the Amazon Web Services API on which unusual levels of activity were recorded.

event_source class-attribute instance-attribute 
event_source: str | None = None

The Amazon Web Services service to which the request was made, such as iam.amazonaws.com or s3.amazonaws.com.

insight_type class-attribute instance-attribute 
insight_type: InsightType | None = None

The type of CloudTrail Insights event, which is either ApiCallRateInsight or ApiErrorRateInsight. The ApiCallRateInsight Insights type analyzes write-only management API calls that are aggregated per minute against a baseline API call volume. The ApiErrorRateInsight Insights type analyzes management API calls that result in error codes.

next_token class-attribute instance-attribute 
next_token: str | None = None

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.

timestamps class-attribute instance-attribute 
timestamps: list[datetime] | None = None

List of timestamps at intervals corresponding to the specified time period.

trail_arn class-attribute instance-attribute 
trail_arn: str | None = None

Specifies the ARN of the trail. This is only returned when Insights is enabled on a trail logging data events.

values class-attribute instance-attribute 
values: list[float] | None = None

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.