2025/11/19 - AWS CloudTrail - 1 new 3 updated api methods
Changes AWS CloudTrail now supports Insights for data events, expanding beyond management events to automatically detect unusual activity on data plane operations.
Returns Insights events generated on a trail that logs data events. You can list Insights events that occurred in a Region within the last 90 days.
ListInsightsData supports the following Dimensions for Insights events:
Event ID
Event name
Event source
All dimensions are optional. The default number of results returned is 50, with a maximum of 50 possible. The response includes a token that you can use to get the next page of results.
The rate of ListInsightsData requests is limited to two per second, per account, per Region. If this limit is exceeded, a throttling error occurs.
See also: AWS API Documentation
Request Syntax
client.list_insights_data(
InsightSource='string',
DataType='InsightsEvents',
Dimensions={
'string': 'string'
},
StartTime=datetime(2015, 1, 1),
EndTime=datetime(2015, 1, 1),
MaxResults=123,
NextToken='string'
)
string
[REQUIRED]
The Amazon Resource Name(ARN) of the trail for which you want to retrieve Insights events.
string
[REQUIRED]
Specifies the category of events returned. To fetch Insights events, specify InsightsEvents as the value of DataType
dict
Contains a map of dimensions. Currently the map can contain only one item.
(string) --
(string) --
datetime
Specifies that only events that occur after or at the specified time are returned. If the specified start time is after the specified end time, an error is returned.
datetime
Specifies that only events that occur before or at the specified time are returned. If the specified end time is before the specified start time, an error is returned.
integer
The number of events to return. Possible values are 1 through 50. The default is 50.
string
The token to use to get the next page of results after a previous API call. This token must be passed in with the same parameters that were specified in the original call. For example, if the original call specified a EventName as a dimension with PutObject as a value, the call with NextToken should include those same parameters.
dict
Response Syntax
{
'Events': [
{
'EventId': 'string',
'EventName': 'string',
'ReadOnly': 'string',
'AccessKeyId': 'string',
'EventTime': datetime(2015, 1, 1),
'EventSource': 'string',
'Username': 'string',
'Resources': [
{
'ResourceType': 'string',
'ResourceName': 'string'
},
],
'CloudTrailEvent': 'string'
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
Events (list) --
A list of events returned based on the InsightSource, DataType or Dimensions specified. The events list is sorted by time. The most recent event is listed first.
(dict) --
Contains information about an event that was returned by a lookup request. The result includes a representation of a CloudTrail event.
EventId (string) --
The CloudTrail ID of the event returned.
EventName (string) --
The name of the event returned.
ReadOnly (string) --
Information about whether the event is a write event or a read event.
AccessKeyId (string) --
The Amazon Web Services access key ID that was used to sign the request. If the request was made with temporary security credentials, this is the access key ID of the temporary credentials.
EventTime (datetime) --
The date and time of the event returned.
EventSource (string) --
The Amazon Web Services service to which the request was made.
Username (string) --
A user name or role name of the requester that called the API in the event returned.
Resources (list) --
A list of resources referenced by the event returned.
(dict) --
Specifies the type and name of a resource referenced by an event.
ResourceType (string) --
The type of a resource referenced by the event returned. When the resource type cannot be determined, null is returned. Some examples of resource types are: Instance for EC2, Trail for CloudTrail, DBInstance for Amazon RDS, and AccessKey for IAM. To learn more about how to look up and filter events by the resource types supported for a service, see Filtering CloudTrail Events.
ResourceName (string) --
The name of the resource referenced by the event returned. These are user-created names whose values will depend on the environment. For example, the resource name might be "auto-scaling-test-group" for an Auto Scaling Group or "i-1234567" for an EC2 Instance.
CloudTrailEvent (string) --
A JSON string that contains a representation of the event returned.
NextToken (string) --
The token to use to get the next page of results after a previous API call. If the token does not appear, there are no more results to return. The token must be passed in with the same parameters as the previous call. For example, if the original call specified a EventName as a dimension with PutObject as a value, the call with NextToken should include those same parameters.
{'InsightSelectors': {'EventCategories': ['Management | Data']}}
Describes the settings for the Insights event selectors that you configured for your trail or event data store. GetInsightSelectors shows if CloudTrail Insights logging is enabled and which Insights types are configured with corresponding event categories. If you run GetInsightSelectors on a trail or event data store that does not have Insights events enabled, the operation throws the exception InsightNotEnabledException
Specify either the EventDataStore parameter to get Insights event selectors for an event data store, or the TrailName parameter to the get Insights event selectors for a trail. You cannot specify these parameters together.
For more information, see Working with CloudTrail Insights in the CloudTrail User Guide.
See also: AWS API Documentation
Request Syntax
client.get_insight_selectors(
TrailName='string',
EventDataStore='string'
)
string
Specifies the name of the trail or trail ARN. If you specify a trail name, the string must meet the following requirements:
Contain only ASCII letters (a-z, A-Z), numbers (0-9), periods (.), underscores (_), or dashes (-)
Start with a letter or number, and end with a letter or number
Be between 3 and 128 characters
Have no adjacent periods, underscores or dashes. Names like my-_namespace and my--namespace are not valid.
Not be in IP address format (for example, 192.168.5.4)
If you specify a trail ARN, it must be in the format:
arn:aws:cloudtrail:us-east-2:123456789012:trail/MyTrail
You cannot use this parameter with the EventDataStore parameter.
string
Specifies the ARN (or ID suffix of the ARN) of the event data store for which you want to get Insights selectors.
You cannot use this parameter with the TrailName parameter.
dict
Response Syntax
{
'TrailARN': 'string',
'InsightSelectors': [
{
'InsightType': 'ApiCallRateInsight'|'ApiErrorRateInsight',
'EventCategories': [
'Management'|'Data',
]
},
],
'EventDataStoreArn': 'string',
'InsightsDestination': 'string'
}
Response Structure
(dict) --
TrailARN (string) --
The Amazon Resource Name (ARN) of a trail for which you want to get Insights selectors.
InsightSelectors (list) --
Contains the Insights types that are enabled on a trail or event data store. It also specifies the event categories on which a particular Insight type is enabled. ApiCallRateInsight and ApiErrorRateInsight are valid Insight types.The EventCategory field can specify Management or Data events or both. For event data store, you can log Insights for management events only.
(dict) --
A JSON string that contains a list of Insights types that are logged on a trail or event data store.
InsightType (string) --
The type of Insights events to log on a trail or event data store. ApiCallRateInsight and ApiErrorRateInsight are valid Insight types.
The ApiCallRateInsight Insights type analyzes write-only management API calls or read and write data API calls that are aggregated per minute against a baseline API call volume.
The ApiErrorRateInsight Insights type analyzes management and data API calls that result in error codes. The error is shown if the API call is unsuccessful.
EventCategories (list) --
Select the event category on which Insights should be enabled.
If EventCategories is not provided, the specified Insights types are enabled on management API calls by default.
If EventCategories is provided, the given event categories will overwrite the existing ones. For example, if a trail already has Insights enabled on management events, and then a PutInsightSelectors request is made with only data events specified in EventCategories, Insights on management events will be disabled.
(string) --
EventDataStoreArn (string) --
The ARN of the source event data store that enabled Insights events.
InsightsDestination (string) --
The ARN of the destination event data store that logs Insights events.
{'TrailName': 'string'}
Response {'TrailARN': 'string'}
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.
See also: AWS API Documentation
Request Syntax
client.list_insights_metric_data(
TrailName='string',
EventSource='string',
EventName='string',
InsightType='ApiCallRateInsight'|'ApiErrorRateInsight',
ErrorCode='string',
StartTime=datetime(2015, 1, 1),
EndTime=datetime(2015, 1, 1),
Period=123,
DataType='FillWithZeros'|'NonZeroData',
MaxResults=123,
NextToken='string'
)
string
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.
string
[REQUIRED]
The Amazon Web Services service to which the request was made, such as iam.amazonaws.com or s3.amazonaws.com.
string
[REQUIRED]
The name of the event, typically the Amazon Web Services API on which unusual levels of activity were recorded.
string
[REQUIRED]
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.
string
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.
datetime
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.
datetime
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.
integer
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.
string
Type of data points to return. Valid values are NonZeroData and FillWithZeros. The default is NonZeroData.
integer
The maximum number of data points to return. Valid values are integers from 1 to 21600. The default value is 21600.
string
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.
dict
Response Syntax
{
'TrailARN': 'string',
'EventSource': 'string',
'EventName': 'string',
'InsightType': 'ApiCallRateInsight'|'ApiErrorRateInsight',
'ErrorCode': 'string',
'Timestamps': [
datetime(2015, 1, 1),
],
'Values': [
123.0,
],
'NextToken': 'string'
}
Response Structure
(dict) --
TrailARN (string) --
Specifies the ARN of the trail. This is only returned when Insights is enabled on a trail logging data events.
EventSource (string) --
The Amazon Web Services service to which the request was made, such as iam.amazonaws.com or s3.amazonaws.com.
EventName (string) --
The name of the event, typically the Amazon Web Services API on which unusual levels of activity were recorded.
InsightType (string) --
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.
ErrorCode (string) --
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.
Timestamps (list) --
List of timestamps at intervals corresponding to the specified time period.
(datetime) --
Values (list) --
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.
(float) --
NextToken (string) --
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.
{'InsightSelectors': {'EventCategories': ['Management | Data']}}
Lets you enable Insights event logging on specific event categories by specifying the Insights selectors that you want to enable on an existing trail or event data store. You also use PutInsightSelectors to turn off Insights event logging, by passing an empty list of Insights types. The valid Insights event types are ApiErrorRateInsight and ApiCallRateInsight, and valid EventCategories are Management and Data.
To enable Insights on an event data store, you must specify the ARNs (or ID suffix of the ARNs) for the source event data store ( EventDataStore) and the destination event data store ( InsightsDestination). The source event data store logs management events and enables Insights. The destination event data store logs Insights events based upon the management event activity of the source event data store. The source and destination event data stores must belong to the same Amazon Web Services account.
To log Insights events for a trail, you must specify the name ( TrailName) of the CloudTrail trail for which you want to change or add Insights selectors.
For Management events Insights: To log CloudTrail Insights on the API call rate, the trail or event data store must log write management events. To log CloudTrail Insights on the API error rate, the trail or event data store must log read or write management events.
For Data events Insights: To log CloudTrail Insights on the API call rate or API error rate, the trail must log read or write data events. Data events Insights are not supported on event data store.
To log CloudTrail Insights events on API call volume, the trail or event data store must log write management events. To log CloudTrail Insights events on API error rate, the trail or event data store must log read or write management events. You can call GetEventSelectors on a trail to check whether the trail logs management events. You can call GetEventDataStore on an event data store to check whether the event data store logs management events.
For more information, see Working with CloudTrail Insights in the CloudTrail User Guide.
See also: AWS API Documentation
Request Syntax
client.put_insight_selectors(
TrailName='string',
InsightSelectors=[
{
'InsightType': 'ApiCallRateInsight'|'ApiErrorRateInsight',
'EventCategories': [
'Management'|'Data',
]
},
],
EventDataStore='string',
InsightsDestination='string'
)
string
The name of the CloudTrail trail for which you want to change or add Insights selectors.
You cannot use this parameter with the EventDataStore and InsightsDestination parameters.
list
[REQUIRED]
Contains the Insights types you want to log on a specific category of events on a trail or event data store. ApiCallRateInsight and ApiErrorRateInsight are valid Insight types.The EventCategory field can specify Management or Data events or both. For event data store, you can log Insights for management events only.
The ApiCallRateInsight Insights type analyzes write-only management API calls or read and write data API calls that are aggregated per minute against a baseline API call volume.
The ApiErrorRateInsight Insights type analyzes management and data API calls that result in error codes. The error is shown if the API call is unsuccessful.
(dict) --
A JSON string that contains a list of Insights types that are logged on a trail or event data store.
InsightType (string) --
The type of Insights events to log on a trail or event data store. ApiCallRateInsight and ApiErrorRateInsight are valid Insight types.
The ApiCallRateInsight Insights type analyzes write-only management API calls or read and write data API calls that are aggregated per minute against a baseline API call volume.
The ApiErrorRateInsight Insights type analyzes management and data API calls that result in error codes. The error is shown if the API call is unsuccessful.
EventCategories (list) --
Select the event category on which Insights should be enabled.
If EventCategories is not provided, the specified Insights types are enabled on management API calls by default.
If EventCategories is provided, the given event categories will overwrite the existing ones. For example, if a trail already has Insights enabled on management events, and then a PutInsightSelectors request is made with only data events specified in EventCategories, Insights on management events will be disabled.
(string) --
string
The ARN (or ID suffix of the ARN) of the source event data store for which you want to change or add Insights selectors. To enable Insights on an event data store, you must provide both the EventDataStore and InsightsDestination parameters.
You cannot use this parameter with the TrailName parameter.
string
The ARN (or ID suffix of the ARN) of the destination event data store that logs Insights events. To enable Insights on an event data store, you must provide both the EventDataStore and InsightsDestination parameters.
You cannot use this parameter with the TrailName parameter.
dict
Response Syntax
{
'TrailARN': 'string',
'InsightSelectors': [
{
'InsightType': 'ApiCallRateInsight'|'ApiErrorRateInsight',
'EventCategories': [
'Management'|'Data',
]
},
],
'EventDataStoreArn': 'string',
'InsightsDestination': 'string'
}
Response Structure
(dict) --
TrailARN (string) --
The Amazon Resource Name (ARN) of a trail for which you want to change or add Insights selectors.
InsightSelectors (list) --
Contains the Insights types you want to log on a specific category of events in a trail or event data store. ApiCallRateInsight and ApiErrorRateInsight are valid Insight types.The EventCategory field can specify Management or Data events or both. For event data store, you can only log Insights for management events only.
(dict) --
A JSON string that contains a list of Insights types that are logged on a trail or event data store.
InsightType (string) --
The type of Insights events to log on a trail or event data store. ApiCallRateInsight and ApiErrorRateInsight are valid Insight types.
The ApiCallRateInsight Insights type analyzes write-only management API calls or read and write data API calls that are aggregated per minute against a baseline API call volume.
The ApiErrorRateInsight Insights type analyzes management and data API calls that result in error codes. The error is shown if the API call is unsuccessful.
EventCategories (list) --
Select the event category on which Insights should be enabled.
If EventCategories is not provided, the specified Insights types are enabled on management API calls by default.
If EventCategories is provided, the given event categories will overwrite the existing ones. For example, if a trail already has Insights enabled on management events, and then a PutInsightSelectors request is made with only data events specified in EventCategories, Insights on management events will be disabled.
(string) --
EventDataStoreArn (string) --
The Amazon Resource Name (ARN) of the source event data store for which you want to change or add Insights selectors.
InsightsDestination (string) --
The ARN of the destination event data store that logs Insights events.