# Working with CloudTrail Insights AWS CloudTrail Insights help AWS users identify and respond to unusual activity associated with API call rates and API error rates by continuously analyzing CloudTrail management and data events. CloudTrail Insights analyzes your past management and data events to establish your normal patterns of API call rates and API error rates, also called the *baseline*. CloudTrail then generates Insights events when the current API call rates or error rates deviate from the baseline. You can collect two types of Insights, each for management and data events. **Management events Insights** + **API call rate** – A measurement of write-only management API calls that occur per minute against a baseline API call volume. To log Insights events on the API call rate for management events, the trail or event data store must enable Insights and log `write` management events. + **API error rate** – A measurement of management API calls that result in error codes. The error is shown if the API call is unsuccessful. To log Insights events on API error rate, the trail or event data store must enable Insights and log `read` or `write` management events, or both `read` and `write` management events. **Data events Insights** + **API call rate** – A measurement of data API calls that occur per minute against a baseline API call volume. To log Insights events on the API call rate, the trail must enable Insights and log data events. + **API error rate** – A measurement of data API calls that result in error codes. The error is shown if the API call is unsuccessful. To log Insights events on API error rate, the trail must enable Insights and log `read` or `write` data events, or both `read` and `write` data events. **Note** Insights events on data events are only supported on trails and not on event data stores. CloudTrail Insights analyzes the management and data events that occur in each Region and generates an Insights event when unusual activity is detected that deviates from the baseline. A CloudTrail Insights event is generated in the same Region as its supporting management or data event is generated. Additional charges apply for Insights events. You will be charged separately if you enable management events Insights for both trails and event data stores, and data events Insights. For more information, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/). **Topics** + [ # Costs for Insights events ](insights-events-costs.md) + [ # Delivery of Insights events ](insights-events-understanding.md) + [ # Logging Insights events with the CloudTrail console ](insights-events-enable.md) + [ # Logging Insights events with the AWS CLI ](insights-events-CLI-enable.md) + [ # Viewing Insights events for trails ](view-insights-events.md) + [ # Viewing Insights events for event data stores ](insights-events-view-lake.md) # Costs for Insights events **Note** Insights events on data events are only supported on trails. When you enable Insights events on an existing trail or event data store, CloudTrail analyzes the past 28 days of management and data events collected by the trail or event data store to establish a baseline of normal activity. After the initial baseline is created, the baseline is recalculated every day on the past 28 days of data. There are no CloudTrail charges for the baseline analysis. After the baseline analysis, you incur CloudTrail charges for any future management and data events analyzed by CloudTrail. You incur charges based on the number of management and data events analyzed for the enabled Insights types. If you choose to log both API call rate and API error rate Insights types for management events for a trail or event data store that logs `read` and `write` management events, the total number of events analyzed will be greater than the total number of recorded management events. This is because CloudTrail will analyze the write-only management events twice, once for calculating the API call rate and again for determining the API error rate. The read-only management events will be analyzed once to calculate the API error rate. Similarly, if you choose to log both API call rate and API error rate Insights types for data events for a trail that logs `read` and `write` data events, the total number of events analyzed will be greater than the total number of recorded data events. This is because CloudTrail will analyze all data events twice, once for calculating the API call rate and again for determining the API error rate. You can identify the charges for Insights for management and data events on your bill by looking for the `InsightsEvents` and `DataInsightsEvents` usage type respectively. For more information, see [Viewing your CloudTrail cost and usage with AWS Cost Explorer](cloudtrail-costs.md). You will incur separate Insights charges for both trails and event data stores, and separate data events Insights for trails. For more information about pricing, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/). **Example 1 – Enable Insights on management events for API call rate and API error rate on a trail** In this first example, you enable Insights on a trail logging management events and choose to collect both Insights types. The trail in this example is logging both `read` and `write` management events. + CloudTrail analyzes the management events logged in the past 28 days to form a baseline. There are no CloudTrail charges for the analysis. + After the baseline is created, the trail logs 300,000 management events, of which 270,000 are `read` management events and 30,000 are `write` management events. + The `write` management events are analyzed twice, once for the API call rate and once for the API error rate (30,000 \$1 2=60,000). + The `read` management events are analyzed once for the API error rate (270,000 \$11=270,000). + The total management events analyzed is 330,000 (60,000 \$1 270,000). You will incur costs for analyzing 330,000 management events for this trail. You will be charged separately if you enable Insights for another trail or an event data store. **Example 2 – Enable Insights on management events for two trails** In this next example, you enable Insights on two trails logging management events, trail A and trail B. You choose to enable API call rate Insights only on trail A and API error rate Insights only on trail B. Both trails log `read` and `write` management events. + CloudTrail analyzes the `write` management events logged in the past 28 days to form a baseline. There are no CloudTrail charges for the analysis. + After the baseline is created, the trails log 800,000 management events, of which 710,000 are `read` events and 90,000 are `write` events. For trail A, the following analysis occurs: + The `write` management events are analyzed once for the API call rate (90,000 \$1 1=90,000). + The `read` management events are not analyzed, because CloudTrail only analyzes `write` management events for API call rate Insights. + The total management events analyzed is 90,000. You will incur costs for analyzing 90,000 management events for trail A. For trail B, the following analysis occurs: + The `write` management events are analyzed once for the API error rate (90,000 \$1 1=90,000). + The `read` management events are analyzed once for the API error rate (710,000 \$11=710,000). + The total management events analyzed is 800,000 (90,000 \$1 710,000). You will incur costs for analyzing 800,000 management events for trail B. **Example 3 – Enable Insights on management events for API call rate and API error rate on a trail and an event data store** In this example, you enable Insights for API call rate and API error rate on both a trail and an event data store logging management events. Both the trail and event data store are logging `read` and `write` management events. You will incur charges for CloudTrail Insights for the trail and event data store separately as you enabled Insights on both. + CloudTrail analyzes the management events logged in the past 28 days to form a baseline. There are no CloudTrail charges for the analysis. + After the baseline is created, the trail and event data store log 500,000 management events, of which 380,000 are `read` management events and 120,000 are `write` management events. For the trail, the following analysis occurs: + The `write` management events are analyzed twice for the trail, once for the API call rate and once for the API error rate (120,000 \$1 2=240,000). + The `read` management events are analyzed once for the trail for the API error rate (380,000 \$11=380,000). + The total management events analyzed for the trail is 620,000 (240,000 \$1 380,000). You will incur costs for analyzing 620,000 management events for the trail. For the event data store, the following analysis occurs: + The `write` management events are analyzed twice for the event data store, once for the API call rate and once for the API error rate (120,000 \$1 2=240,000). + The `read` management events are analyzed once for the event data store for the API error rate (380,000 \$11=380,000). + The total management events analyzed for the event data store is 620,000 (240,000 \$1 380,000). You will incur costs for analyzing 620,000 management events for the event data store. **Example 4 – Enable management events Insights and data events Insights for API call rate and API error rate on a trail** In this final example, you enable Insights on management and data events. The trail in this example is logging `read` and `write` management and data events. + CloudTrail analyzes the management and data events logged in the past 28 days to form a baseline. There are no CloudTrail charges for the analysis. + After the baseline is created, the trail logs 300,000 management events, of which 270,000 are read management events and 30,000 are write management events. The trail also logs 400,000 data events, of which 340,000 are read data events and 60,000 are write data events. + The `write` management events are analyzed twice, once for the API call rate and once for the API error rate (30,000 \$1 2=60,000). The `read` management events are analyzed once for the API error rate (270,000 \$11=270,000). The total management events analyzed is 330,000 (60,000 \$1 270,000). + The `read` and `write` data events are analyzed twice, once for the API call rate and once for the API error rate (400,000 \$1 2). The total data events analyzed is 800,000. + You will incur costs for analyzing 1,130,000 management and data events for this trail. # Delivery of Insights events Unlike other types of events that CloudTrail captures, Insights events are logged only when CloudTrail detects changes in your account's API usage that differ significantly from the account's typical usage patterns. Where CloudTrail delivers events and how long it takes to receive Insights events differs between trails and event data stores. **Note** Insights events on data events are only supported on trails. **Insights events delivery for trails** If you've enabled Insights events on a trail and CloudTrail detects unusual activity, CloudTrail delivers Insights events to the `/CloudTrail-Insight` folder in the chosen destination S3 bucket for your trail. After you enable CloudTrail Insights for the first time on a trail, CloudTrail may take up to 36 hours to begin delivering Insights events, provided that unusual activity is detected during that time. If you turn off Insights events logging on a trail and then re-enable Insights events, or stop and restart logging on a trail, it can take up to 36 hours for CloudTrail to restart delivery of Insights events, provided that unusual activity is detected during that time. **Insights events delivery for event data stores** If you've enabled Insights events on a source event data store, CloudTrail delivers Insights events to the destination event data store. After you enable CloudTrail Insights for the first time on the source event data store, CloudTrail may take up to 7 days to begin delivering Insights events to the destination event data store, provided that unusual activity is detected during that time. If you turn off Insights events logging on a source event data store and then re-enable Insights events, or stop and restart event ingestion on a source event data store, it can take up to 7 days for CloudTrail to restart delivery of Insights events, provided that unusual activity is detected during that time. Additional charges apply for ingesting Insights events in CloudTrail Lake. You will be charged separately if you enable Insights for both trails and event data stores. For information about CloudTrail pricing, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/). # Logging Insights events with the CloudTrail console This section describes how you can enable Insights events on an existing trail or event data store using the CloudTrail console. For more information about how to create a new trail to log Insights events, see [Creating a trail with the console](cloudtrail-create-a-trail-using-the-console-first-time.md#creating-a-trail-in-the-console). For more information about how to create a new event data store to collect Insights events, see [Create an event data store for Insights events with the console](query-event-data-store-insights.md). **Topics** + [ ## Enabling CloudTrail Insights on an existing trail with the console ](#insights-events-enable-trail) + [ ## Enabling CloudTrail Insights on an existing event data store with the console ](#insights-events-enable-lake) ## Enabling CloudTrail Insights on an existing trail with the console Use the following procedure to enable CloudTrail Insights on an existing trail. 1. In the left navigation pane of the CloudTrail console, open the **Trails** page, and choose a trail name. 1. In **Insights events**, choose **Edit**. **Note** Additional charges apply for logging Insights events. For CloudTrail pricing, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/). 1. In **Event type**, choose **Insights events**. 1. In **Insights events** choose **management events** or **data events** 1. Under **Insights types**, choose **API call rate, API error rate,** or both. Your trail must be logging **Write** management or data events to log Insights events for **API call rate**. Your trail must be logging **Read** or **Write** management or data to log Insights events for **API error rate**. 1. Choose **Save changes** to save your changes. CloudTrail may take up to 36 hours to begin delivering Insights events after you enable Insights events on a trail, provided that unusual activity is detected during that time. ## Enabling CloudTrail Insights on an existing event data store with the console Use the following procedure to enable CloudTrail Insights on an existing event data store. Additional charges apply for ingesting Insights events in CloudTrail Lake. You will be charged separately if you enable Insights for both trails and event data stores. For information about CloudTrail pricing, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/). **Note** You can only enable CloudTrail Insights on event data stores containing CloudTrail management events. You cannot enable CloudTrail Insights on other event data store types. 1. In the left navigation pane of the CloudTrail console, under **Lake**, choose **Event data stores**. 1. Choose the event data store name. 1. In **Management events**, choose **Edit**. 1. Choose **Enable Insights events capture**. 1. Choose the destination event store that will collect Insights events. The destination event data store will collect Insights events based upon the management event activity in this event data store. For information about how to create the destination event data store, see [To create a destination event data store that logs Insights events](query-event-data-store-insights.md#query-event-data-store-insights-procedure). 1. Choose the Insights types. You can choose **API call rate**, **API error rate**, or both. You must be logging **Write** management events to log Insights events for **API call rate**. You must be logging **Read** or **Write** management events to log Insights events for **API error rate**. 1. Choose **Save changes** to save your changes. CloudTrail may take up to 7 days to begin delivering Insights events, provided that unusual activity is detected during that time. # Logging Insights events with the AWS CLI You can configure your trails and event data stores to log Insights events using the AWS CLI. **Note** For Management events Insights: To log Insights events on the API call rate, the trail or event data store must log `write` management events. To log Insights events on the API error rate, the trail or event data store must log `read` or `write` management. For Data events Insights: To log Insights events on the API call rate or API error rate, the trail must log `read` or `write` data events. **Topics** + [ ## Logging Insights events for a trail using the AWS CLI ](#insights-events-CLI-enable-trails) + [ ## Logging Insights events for an event data store using the AWS CLI ](#insights-events-CLI-enable-lake) ## Logging Insights events for a trail using the AWS CLI To return the current Insights selectors for a trail, run the `get-insight-selectors` command. ``` aws cloudtrail get-insight-selectors --trail-name TrailName ``` The following example response shows the Insights selectors for a trail named `insights-trail`. ``` { "TrailARN": "arn:aws:cloudtrail:us-east-1:123456789012:trail/insights-trail", "InsightSelectors": [ { "InsightType": "ApiCallRateInsight", "EventCategories": [ "Management", "Data" ] }, { "InsightType": "ApiErrorRateInsight", "EventCategories": [ "Management", "Data" ] } ] } ``` If the trail does not have Insights enabled, the **get-insight-selectors** command returns the following error message: "An error occurred (InsightNotEnabledException) when calling the GetInsightSelectors operation: Trail arn:aws:cloudtrail:us-east-1:123456789012:trail/trailName does not have Insights enabled. Edit the trail settings to enable Insights, and then try the operation again." To configure your trail to log Insights events, run the `put-insight-selectors` command. The following example shows how to configure your trail to include Insights events. Insights selector values can be `ApiCallRateInsight`, `ApiErrorRateInsight`, or both. Each InsightType can be enabled for management EventCategory or data EventCategory or both. ``` aws cloudtrail put-insight-selectors --trail-name TrailName --insight-selectors '[{"InsightType": "ApiCallRateInsight", "EventCategories": ["Data"]},{"InsightType": "ApiErrorRateInsight", "EventCategories": ["Data", "Management"]}]' ``` The following result shows the Insights event selector that is configured for the trail. ``` { "TrailARN": "arn:aws:cloudtrail:us-east-1:123456789012:trail/TrailName", "InsightSelectors": [ { "InsightType": "ApiErrorRateInsight", "EventCategories": [ "Data" ] }, { "InsightType": "ApiCallRateInsight", "EventCategories": [ "Data", "Management" ] } ] } ``` ## Logging Insights events for an event data store using the AWS CLI To enable Insights on an event data store, you must have a source event data store that logs management events and a destination event data store that logs Insights events. To view whether Insights events are enabled on an event data store, run the **get-insight-selectors** command. ``` aws cloudtrail get-insight-selectors --event-data-store arn:aws:cloudtrail:us-east-1:123456789012:eventdatastore/EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE ``` To view whether an event data store is configured to receive Insights events or management events, run the **get-event-data-store** command. ``` aws cloudtrail get-event-data-store --event-data-store arn:aws:cloudtrail:us-east-1:123456789012:eventdatastore/EXAMPLE-d483-5c7d-4ac2-adb5dEXAMPLE ``` If an event data store is configured to receive Insights events, its `eventCategory` will be set to `Insight`. The following procedure shows you how to create the destination and source event data stores and then enable Insights events. 1. Run the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudtrail/create-event-data-store.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudtrail/create-event-data-store.html) command to create a destination event data store that collects Insights events. The value for `eventCategory` must be `Insight`. Replace *retention-period-days* with the number of days you would like to retain events in your event data store. If you are signed in with the management account for an AWS Organizations organization, include the `--organization-enabled` parameter if you want to give your [delegated administrator](cloudtrail-delegated-administrator.md) access to the event data store. ``` aws cloudtrail create-event-data-store \ --name insights-event-data-store \ --no-multi-region-enabled \ --retention-period retention-period-days \ --advanced-event-selectors '[ { "Name": "Select Insights events", "FieldSelectors": [ { "Field": "eventCategory", "Equals": ["Insight"] } ] } ]' ``` The following is an example response. ``` { "Name": "insights-event-data-store", "ARN": "arn:aws:cloudtrail:us-east-1:111122223333:eventdatastore/EXAMPLEf852-4e8f-8bd1-bcf6cEXAMPLE", "AdvancedEventSelectors": [ { "Name": "Select Insights events", "FieldSelectors": [ { "Field": "eventCategory", "Equals": [ "Insight" ] } ] } ], "MultiRegionEnabled": false, "OrganizationEnabled": false, "BillingMode": "EXTENDABLE_RETENTION_PRICING", "RetentionPeriod": "90", "TerminationProtectionEnabled": true, "CreatedTimestamp": "2023-11-08T15:22:33.578000+00:00", "UpdatedTimestamp": "2023-11-08T15:22:33.714000+00:00" } ``` You will use the `ARN` (or ID suffix of the ARN) from the response as the value for the `--insights-destination` parameter in step 3. 1. Run the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudtrail/create-event-data-store.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudtrail/create-event-data-store.html) command to create a source event data store that logs management events. By default, event data stores log all management events. You don't need to specify the advanced event selectors if you want to log all management events. Replace *retention-period-days* with the number of days you would like to retain events in your event data store. If you are creating an organization event data store, include the `--organization-enabled` parameter. ``` aws cloudtrail create-event-data-store --name source-event-data-store --retention-period retention-period-days ``` The following is an example response. ``` { "EventDataStoreArn": "arn:aws:cloudtrail:us-east-1:111122223333:eventdatastore/EXAMPLE9952-4ab9-49c0-b788-f4f3EXAMPLE", "Name": "source-event-data-store", "Status": "CREATED", "AdvancedEventSelectors": [ { "Name": "Default management events", "FieldSelectors": [ { "Field": "eventCategory", "Equals": [ "Management" ] } ] } ], "MultiRegionEnabled": true, "OrganizationEnabled": false, "BillingMode": "EXTENDABLE_RETENTION_PRICING", "RetentionPeriod": 90, "TerminationProtectionEnabled": true, "CreatedTimestamp": "2023-11-08T15:25:35.578000+00:00", "UpdatedTimestamp": "2023-11-08T15:25:35.714000+00:00" } ``` You will use the `ARN` (or ID suffix of the ARN) from the response as the value for the `--event-data-store` parameter in step 3. 1. Run the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudtrail/put-insight-selectors.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudtrail/put-insight-selectors.html) command to enable Insights events. Insights selector values can be `ApiCallRateInsight`, `ApiErrorRateInsight`, or both. For the `--event-data-store` parameter, specify the ARN (or ID suffix of the ARN) of the source event data store that logs management events and will enable Insights. For the `--insights-destination` parameter, specify the ARN (or ID suffix of the ARN) of the destination event data store that will log Insights events. ``` aws cloudtrail put-insight-selectors --event-data-store arn:aws:cloudtrail:us-east-1:111122223333:eventdatastore/EXAMPLE9952-4ab9-49c0-b788-f4f3EXAMPLE --insights-destination arn:aws:cloudtrail:us-east-1:111122223333:eventdatastore/EXAMPLEf852-4e8f-8bd1-bcf6cEXAMPLE --insight-selectors '[{"InsightType": "ApiCallRateInsight"},{"InsightType": "ApiErrorRateInsight"}]' ``` The following result shows the Insights event selector that is configured for the event data store. ``` { "EventDataStoreARN": "arn:aws:cloudtrail:us-east-1:111122223333:eventdatastore/EXAMPLE9952-4ab9-49c0-b788-f4f3EXAMPLE", "InsightsDestination": "arn:aws:cloudtrail:us-east-1:111122223333:eventdatastore/EXAMPLEf852-4e8f-8bd1-bcf6cEXAMPLE", "InsightSelectors": [ { "InsightType": "ApiErrorRateInsight" }, { "InsightType": "ApiCallRateInsight" } ] } ``` After you enable CloudTrail Insights for the first time on an event data store, CloudTrail may take up to 7 days to begin delivering Insights events, provided that unusual activity is detected during that time. # Viewing Insights events for trails This section describes how you can lookup the last 90 days of Insights events for a trail with CloudTrail Insights enabled. For information about how to view CloudTrail Insights for an event data store, see [Viewing the Insights dashboard for an event data store](insights-events-view-lake.md#insights-events-view-lake-dashboard). You can view, filter, and download the last 90 days of Insights events for a trail from the **Insights** page on the console. You can fetch the last 90 days of Insights events programmatically: + For Trails logging management events by running the AWS CLI [https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/lookup-events.html](https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/lookup-events.html) command, or the [https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_LookupEvents.html](https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_LookupEvents.html) API operation. + For Trails logging data events by running the AWS CLI [https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/list-insights-data.html](https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/list-insights-data.html) command, or the [https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_ListInsightsData.html](https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_ListInsightsData.html) API operation. For descriptions of Insights events record fields for trails, see [CloudTrail record contents for Insights events for trails](cloudtrail-insights-fields-trails.md). **Note** The **Insights** page and AWS CLI `lookup-events` or `list-insights-data` command only list Insights events if you've enabled Insights on a trail that is logging management or data events. For information about enabling Insights on a trail, see [Enabling CloudTrail Insights on an existing trail with the console](insights-events-enable.md#insights-events-enable-trail) and [Logging Insights events for a trail using the AWS CLI](insights-events-CLI-enable.md#insights-events-CLI-enable-trails). To log Insights events on the API call rate, the trail must log `write` management or data events. To log Insights events on the API error rate, the trail must log `read` or `write` management or data events. **Topics** + [ # Viewing Insights events for trails with the console ](view-insights-events-console.md) + [ # Viewing Insights events for trails with the AWS CLI ](view-insights-events-cli.md) # Viewing Insights events for trails with the console This section describes how to view, look up, and download the last 90 days of Insights events for a trail from the **Insights** page on the CloudTrail console. For information about how to view CloudTrail Insights for an event data store, see [Viewing the Insights dashboard for an event data store](insights-events-view-lake.md#insights-events-view-lake-dashboard). After Insights events are logged for a trail, the events are shown on the **Insights** page for 90 days. You cannot manually delete events from the **Insights** page. Since Insights events enabled for a trail are stored in the Amazon S3 bucket configured for that trail, removing the Insights events from the bucket will delete those events. You can monitor your trail logs and be notified when specific Insights events occur by enabling CloudWatch Logs. For more information, see [Monitoring CloudTrail Log Files with Amazon CloudWatch Logs](monitor-cloudtrail-log-files-with-cloudwatch-logs.md). **Note** CloudTrail Insights events must be enabled on your trail to see Insights events in the console. Allow up to 36 hours for CloudTrail to deliver the first Insights events, provided that unusual activity is detected during that time. For Management events Insights: To log Insights events on the API call rate, the trail must log `write` management events. To log Insights events on the API error rate, the trail must log `read` or `write` management events. For Data events Insights: To log Insights events on the API call rate or API error rate, the trail must log `read` or `write` data events. **To view Insights events** 1. Sign in to the AWS Management Console and open the CloudTrail console at [https://console.aws.amazon.com/cloudtrail/home/](https://console.aws.amazon.com/cloudtrail/home/). 1. In the navigation pane, choose **Insights** to see all Insights events logged in your account in the last 90 days. You can also view the five most recent Insights events from the **Dashboards** page. 1. On the **Insights** page, you can select either the management events Insights or data events Insights tab 1. You can filter Insights events by event source, event name, or event ID. For more information about filtering Insights events, see [Filtering Insights events](#filtering-insights-events). 1. You can further limit the list to a **Relative range** or **Absolute range**. **Contents** + [ ## Filtering Insights events ](#filtering-insights-events) + [ ## Viewing Insights events details ](#viewing-details-for-an-event) + [ ## Zoom, pan, and download graph ](#viewing-insight-details-zoom) + [ ## Change graph time span settings ](#viewing-insight-details-timespan) + [ ## Downloading Insights events ](#downloading-insights-events) ## Filtering Insights events By default, events on the **Insights** page are shown in reverse chronological order by event start time. You can filter the list by choosing from one of the following three attributes: **Event name** The name of the event, typically the AWS API on which unusual levels of activity were recorded. **Event source** The AWS service to which the request was made, such as `iam.amazonaws.com` or `s3.amazonaws.com`. If you choose to filter by event source, you can scroll through a list of event sources. **Event ID** The ID of the Insights event. Event IDs are not shown in the **Insights** page table, but they are an attribute on which you can filter Insights events. The event IDs of management or data events that are analyzed to generate Insights events are different from the event IDs of Insights events. ![\[The CloudTrail Insights event list filter.\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/images/insights_events_filter.png) The following list describes the attributes of an event, which are not filterable: **Insight type** The type of CloudTrail Insights event, which is either **API call rate** or **API error rate**. The **API call rate** insight type analyzes write-only management or data API calls that are aggregated per minute against a baseline API call volume. The **API error rate** insight type analyzes management or data API calls that result in error codes. The error is shown if the API call is unsuccessful. **Event start time** The start time of the Insights event, measured as the first minute in which unusual activity was recorded. This attribute is shown in the **Insights** table, but you cannot filter on event start time in the console. **Baseline average** Baseline represents the normal pattern of API call rate or error rate activity, calculated daily. The baseline average is the average of these daily baselines over the seven days preceding the start of an Insights event. While this period is generally seven days, CloudTrail rounds the calculation period to a whole number of days, so the exact baseline duration may vary slightly. **Insight average** The average number of calls to an API, or the average number of a specific error that was returned on calls to an API, that triggered the Insights event. The CloudTrail Insights average for the start event is the rate of occurrences that triggered the Insights event. Typically, this is the first minute of unusual activity. The Insights average for the end event is the rate of occurrences over the duration of the unusual activity, between the start Insights event and the end Insights event. **Rate change** The difference between the value of **Baseline average** and **Insight average**, measured as a percentage. For example, if the baseline average of an `AccessDenied` error occurring is 1.0, and the Insight average is 3.0, the rate change is 300%. A rate change for an Insight average that exceeds a baseline average shows an up-arrow next to the value. If the Insights event was logged because the activity is below the baseline average, **Rate change** shows a down-arrow next to the percentage. If there are no events logged for the attribute or time that you choose, the results list is empty. You can apply only one attribute filter in addition to the time range. If you choose a different attribute filter, your specified time range is preserved. The following steps describe how to filter by attribute. **To filter by attribute** 1. To filter the results by an attribute, choose a lookup attribute from the dropdown menu, and then type or choose a value in the **Enter a lookup value** box. 1. To remove an attribute filter, choose the **X** on the right of the attribute filter box. The following steps describe how to filter by a start and end date and time. **To filter by a start and end date and time** 1. From **Filter by date and time**, choose one of the following: + **Absolute range** - Lets you choose a specific time. Go on to the next step. + **Relative range** - Selected by default. Lets you choose a time period relative to the start time of an Insights event. Go on to step 3. 1. To set an **Absolute range**, do the following. 1. Choose the day that you want the time range to start. Enter a start time on the selected day. To enter a date manually, type the date in the format `yyyy/mm/dd`. The start and end times use a 24-hour clock, and values must be in the format `hh:mm:ss`. For example, to indicate a 6:30 p.m. start time, enter **18:30:00**. 1. Choose an end date for the range on the calendar, or specify an end date and time below the calendar. Choose **Apply**. 1. To set a **Relative range**, do the following. 1. Choose a preset time period relative to the start time of Insights events. Preset time ranges include 30 minutes, 1 hour, 12 hours, or 1 day. To specify a custom time range, choose **Custom**. 1. When you have set the relative time that you want, choose **Apply**. 1. To remove a time range filter, choose the calendar icon on the right of the **Filter by date and time** box, and then choose **Clear and dismiss**. ## Viewing Insights events details 1. Choose an Insights event in the results list to show its details. The details page for an Insights event shows a graph of the unusual activity timeline. ![\[A CloudTrail Insights detail page showing unusual API activity.\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/images/insights_event_view.png) 1. Hover over the highlighted bands to show the start time and duration of each Insights event in the graph. ![\[Insights event statistics shown after hovering over an Insights event.\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/images/insights_event_statistics.png) The following information is shown in the **Additional information** area of the graph: + **Insight type**. This can be API call rate or API error rate. + **Trigger**. This is a link to the **Cloudtrail events** tab, which lists the management or data events that were analyzed to determine that unusual activity occurred. + **API calls per minute** or **Errors per minute** + **Baseline average** - The typical rate of occurrences per minute on the API on which the Insights event was logged, as measured within approximately the preceding seven days, in a specific Region in your account. + **Insights average** - The rate of occurrences per minute on this API that triggered the Insights event. The CloudTrail Insights average for the start event is the rate of calls or errors per minute on the API that triggered the Insights event. Typically, this is the first minute of unusual activity. The Insights average for the end event is the rate of API calls or errors per minute over the duration of the unusual activity, between the start Insights event and the end Insights event. + **Event source**. The AWS service endpoint on which the unusual number of API calls or errors were logged. In the preceding image, the source is `ec2.amazonaws.com`, which is the service endpoint for Amazon EC2. + **Start event ID** - The ID of the Insights event that was logged at the start of unusual activity. + **End event ID** - The ID of the Insights event that was logged at the end of unusual activity. + **Shared event ID** - In Insights events, the **Shared event ID** is a GUID that is generated by CloudTrail Insights to uniquely identify a start and end pair of Insights events. **Shared event ID** is common between the start and the end Insights event, and helps to create a correlation between both events to uniquely identify unusual activity. 1. Choose the **Attributions** tab to view information about the user identities, user agents, and on API call rate Insights events, error codes correlated with unusual and baseline activity. A maximum of five user identities, five user agents, and five error codes are shown in tables on the **Attributions** tab, sorted by an average of the count of activity, in descending order from highest to lowest. 1. On the **CloudTrail events** tab, view related events that CloudTrail analyzed to determine that unusual activity occurred. By default, a filter is already applied for the Insights event name, which is also the name of the related API. The **CloudTrail events** tab shows CloudTrail management or data events related to the subject API that occurred between the start time (minus one minute) and end time (plus one minute) of the Insights event. As you select other Insights events in the graph, the events shown in the **CloudTrail events** table change. These events help you perform deeper analysis to determine the probable cause of an Insights event and reasons for unusual API activity. To show all CloudTrail events that were logged during the Insights event duration, and not only those for the related API, turn off the filter. 1. Choose the **Insights event record** tab to view the Insights start and end events in JSON format. 1. Choosing the linked **Event source** returns you to the **Insights** page, filtered by that event source. ## Zoom, pan, and download graph You can zoom, pan, and reset the axes of the graph on the Insights event details page by using a toolbar in the upper right corner. ![\[Download as PNG, zoom, pan, zoom in, zoom out, and reset axes command toolbar.\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/images/insights_details_custom_widgets.png) From left to right, the command buttons on the graph toolbar do the following: + **Download plot as a PNG** - Download the graph image shown on the details page, and save it in PNG format. + **Zoom** - Drag to select an area on the graph that you want to enlarge and see in greater detail. + **Pan** - Shift the graph to see adjacent dates or times. + **Reset axes** - Change graph axes back to the original, clearing zoom and pan settings. ## Change graph time span settings You can change the time span—the selected duration of the events shown on the *x* axis—that is shown in the graph by choosing a setting in the graph's upper right corner. ![\[Time span control for an Insights event.\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/images/insights_details_timespan.png) ## Downloading Insights events You can download recorded Insights event history as a file in CSV or JSON format. Use filters and time ranges to reduce the size of the file you download. **Note** CloudTrail event history files are data files that contain information (such as resource names) that can be configured by individual users. Some data can potentially be interpreted as commands in programs used to read and analyze this data (CSV injection). For example, when CloudTrail events are exported to CSV and imported to a spreadsheet program, that program might warn you about security concerns. As a security best practice, disable links or macros from downloaded event history files. 1. Specify the filter and time range for events you want to download. For example, you can specify the event name, `StartInstances`, and specify a time range for the last 12 hours of activity. 1. Choose **Download events**, and then choose **Download as CSV** or **Download as JSON**. You are prompted to choose a location to save the file. **Note** Your download might take some time to finish. For faster results, before you start the download process, use a more specific filter or a shorter time range to narrow the results. 1. After your download is complete, open the file to view the events that you specified. 1. To cancel your download, choose **Cancel**. If you cancel a download before it is finished, a CSV or JSON file on your local computer might contain only part of your events. # Viewing Insights events for trails with the AWS CLI This section describes how to use the AWS CLI `lookup-events` and `list-insights-data` command to lookup the last 90 days of Insights events for a trail with Insights events enabled. For information about how to enable CloudTrail Insights on a trail, see [Logging Insights events for a trail using the AWS CLI](insights-events-CLI-enable.md#insights-events-CLI-enable-trails). **Note** You cannot use the `lookup-events` or `list-insights-data`command to lookup Insights events for an event data store, however, CloudTrail Lake offers a number of sample queries for Insights event data stores. For more information, see [Viewing sample queries for Insights events](insights-events-view-lake.md#insights-events-lake-queries). The `lookup-events` command has the following options: + `--end-time` + `--event-category` + `--max-results` + `--start-time` + `--lookup-attributes` + `--next-token` + `--generate-cli-skeleton` + `--cli-input-json` The `list-insights-data` command has the following options: + `--end-time` + `--data-type` + `--max-results` + `--start-time` + `--dimensions` + `--next-token` + `--generate-cli-skeleton` + `--cli-input-json` For general information about using the AWS Command Line Interface, see the [AWS Command Line Interface User Guide](https://docs.aws.amazon.com/cli/latest/userguide/). **Contents** + [ ## Prerequisites ](#aws-cli-prerequisites-for-insights) + [ ## Getting command line help ](#getting-command-line-help-insights) + [ ## Looking up Insights events for management events ](#looking-up-management-insights-with-the-aws-cli) + [ ## Looking up Insights events for data events ](#looking-up-data-insights-with-the-aws-cli) + [ ## Specifying the number of Insights events for management events to return ](#specify-the-number-of-management-insights-to-return) + [ ## Specifying the number of Insights events for data events to return ](#specify-the-number-of-data-insights-to-return) + [ ## Looking up Insights events for management events by time range ](#look-up-management-insights-by-time-range) + [ ## Looking up Insights events for data events by time range ](#look-up-data-insights-by-time-range) + [ ## Looking up Insights events for management events by attribute ](#look-up-management-insights-by-attributes) + [ ### Attribute lookup examples ](#attribute-lookup-example-insights) + [ ## Looking up Insights events for data events by dimension ](#look-up-data-insights-by-attributes) + [ ### Dimension lookup examples ](#dimension-lookup-example-insights) + [ ## Specifying the next page of results for Insights events for management events ](#specify-next-page-of-management-results) + [ ## Specifying the next page of results for Insights events for management events ](#specify-next-page-of-data-results) + [ ## Getting JSON input from a file for Insights events for management events ](#json-input-from-file-managemenet-insights) + [ ## Getting JSON input from a file for Insights events for data events ](#json-input-from-file-data-insights) + [ ## Lookup output fields ](#view-insights-events-cli-output-fields) ## Prerequisites + To run AWS CLI commands, you must install the AWS CLI. For more information, see [Get started with the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html). + Make sure your AWS CLI version is greater than 1.6.6. To verify the CLI version, run **aws --version** on the command line. + To set the account, Region, and default output format for an AWS CLI session, use the **aws configure** command. For more information, see [ Configuring the AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html). + To log Insights events on the API call rate, the trail must log `write` management events. To log Insights events on the API error rate, the trail must log `read` or `write` management events. **Note** The CloudTrail AWS CLI commands are case-sensitive. ## Getting command line help To see the command line help for `lookup-events`, type the following command. ``` aws cloudtrail lookup-events help ``` ## Looking up Insights events for management events To see the 50 latest Insights events, type the following command. ``` aws cloudtrail lookup-events --event-category insight ``` A returned event looks similar to the following example, ``` { "NextToken": "kbOt5LlZe++mErCebpy2TgaMgmDvF1kYGFcH64JSjIbZFjsuvrSqg66b5YGssKutDYIyII4lrP4IDbeQdiObkp9YAlju3oXd12juEXAMPLE=", "Events": [ { "eventVersion": "1.09", "eventTime": "2024-12-11T16:52:00Z", "awsRegion": "us-east-1", "eventID": "18378b1e-3653-433d-ba1e-aa11a5958f0c", "eventType": "AwsCloudTrailInsight", "recipientAccountId": "888888888888", "sharedEventID": "fccb064f-dd07-4822-97c0-11115d8b91d4", "insightDetails": { "state": "Start", "eventSource": "cloudtrail.amazonaws.com", "eventName": "DescribeQuery", "insightType": "ApiErrorRateInsight", "errorCode": "QueryIdNotFoundException", "sourceEventCategory": "Management", "insightContext": { "statistics": { "baseline": { "average": 0 }, "insight": { "average": 1.2 }, "insightDuration": 5, "baselineDuration": 11092 }, "attributions": [ { "attribute": "userIdentityArn", "insight": [ { "value": "arn:aws:sts::888888888888:assumed-role/Admin", "average": 1.2 } ], "baseline": [] }, { "attribute": "userAgent", "insight": [ { "value": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36", "average": 1.2 } ], "baseline": [] } ] } }, "eventCategory": "Insight" }, { "eventVersion": "1.09", "eventTime": "2024-12-11T16:53:00Z", "awsRegion": "us-east-1", "eventID": "b32f10a0-f039-419a-bad7-e95468930a4f", "eventType": "AwsCloudTrailInsight", "recipientAccountId": "888888888888", "sharedEventID": "fccb064f-dd07-4822-97c0-11115d8b91d4", "insightDetails": { "state": "End", "eventSource": "cloudtrail.amazonaws.com", "eventName": "DescribeQuery", "insightType": "ApiErrorRateInsight", "errorCode": "QueryIdNotFoundException", "sourceEventCategory": "Management", "insightContext": { "statistics": { "baseline": { "average": 0 }, "insight": { "average": 6 }, "insightDuration": 1, "baselineDuration": 11092 }, "attributions": [ { "attribute": "userIdentityArn", "insight": [ { "value": "arn:aws:sts::888888888888:assumed-role/Admin", "average": 6 } ], "baseline": [] }, { "attribute": "userAgent", "insight": [ { "value": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36", "average": 6 } ], "baseline": [] } ] } }, "eventCategory": "Insight" } ] } ``` For an explanation of the lookup-related fields in the output, see [Lookup output fields](#view-insights-events-cli-output-fields) in this topic. For an explanation of fields in the Insights event, see [CloudTrail record contents for Insights events for trails](cloudtrail-insights-fields-trails.md). ## Looking up Insights events for data events To see the 50 latest Insights events, type the following command. ``` aws cloudtrail list-insights-data --data-type InsightsEvents --insight-source arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName ``` A returned event looks similar to the following example, ``` { "NextToken": "kbOt5LlZe++mErCebpy2TgaMgmDvF1kYGFcH64JSjIbZFjsuvrSqg66b5YGssKutDYIyII4lrP4IDbeQdiObkp9YAlju3oXd12juEXAMPLE=", "Events": [ { "eventVersion": "1.09", "eventTime": "2024-12-11T16:52:00Z", "awsRegion": "us-east-2", "eventID": "18378b1e-3653-433d-ba1e-aa11a5958f0c", "eventType": "AwsCloudTrailInsight", "recipientAccountId": "123456789012", "sharedEventID": "fccb064f-dd07-4822-97c0-11115d8b91d4", "insightDetails": { "state": "Start", "eventSource": "s3.amazonaws.com", "eventName": "PutObject", "insightType": "ApiErrorRateInsight", "errorCode": "InvalidRequest", "sourceEventCategory": "Data", "insightContext": { "statistics": { "baseline": { "average": 0 }, "insight": { "average": 1.2 }, "insightDuration": 5, "baselineDuration": 11092 }, "attributions": [ { "attribute": "userIdentityArn", "insight": [ { "value": "arn:aws:sts::123456789012:assumed-role/Admin", "average": 1.2 } ], "baseline": [] }, { "attribute": "userAgent", "insight": [ { "value": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36", "average": 1.2 } ], "baseline": [] } ] }, "insightSource": "arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName" }, "eventCategory": "Insight" }, { "eventVersion": "1.09", "eventTime": "2024-12-11T16:53:00Z", "awsRegion": "us-east-1", "eventID": "b32f10a0-f039-419a-bad7-e95468930a4f", "eventType": "AwsCloudTrailInsight", "recipientAccountId": "123456789012", "sharedEventID": "fccb064f-dd07-4822-97c0-11115d8b91d4", "insightDetails": { "state": "End", "eventSource": "s3.amazonaws.com", "eventName": "PutObject", "insightType": "ApiErrorRateInsight", "errorCode": "InvalidRequest", "sourceEventCategory": "Data", "insightContext": { "statistics": { "baseline": { "average": 0 }, "insight": { "average": 6 }, "insightDuration": 1, "baselineDuration": 11092 }, "attributions": [ { "attribute": "userIdentityArn", "insight": [ { "value": "arn:aws:sts::123456789012:assumed-role/Admin", "average": 6 } ], "baseline": [] }, { "attribute": "userAgent", "insight": [ { "value": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36", "average": 6 } ], "baseline": [] } ] }, "insightSource": "arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName" }, "eventCategory": "Insight" } ] } ``` ## Specifying the number of Insights events for management events to return To specify the number of Insights events for management events to return, type the following command. ``` aws cloudtrail lookup-events --event-category insight --max-results ``` The default value for **, if it is not specified, is 50. Possible values are 1 through 50. The following example returns one result. ``` aws cloudtrail lookup-events --event-category insight --max-results 1 ``` ## Specifying the number of Insights events for data events to return To specify the number of Insights events for data events to return, type the following command. ``` aws cloudtrail list-insights-data --data-type InsightsEvents --insight-source arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName --max-results ``` The default value for **, if it is not specified, is 50. Possible values are 1 through 50. The following example returns one result. ``` aws cloudtrail list-insights-data --data-type InsightsEvents --insight-source arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName --max-results 1 ``` ## Looking up Insights events for management events by time range Insights events for management events from the past 90 days are available for lookup. To specify a time range, type the following command. ``` aws cloudtrail lookup-events --event-category insight --start-time --end-time ``` `--start-time ` specifies, in UTC, that only Insights 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. `--end-time ` specifies, in UTC, that only Insights 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. The default start time is the earliest date that data is available within the last 90 days. The default end time is the time of the event that occurred closest to the current time. All timestamps are shown in UTC. ## Looking up Insights events for data events by time range Insights events for data events from the past 90 days are available for lookup. To specify a time range, type the following command. ``` aws cloudtrail list-insights-data --data-type InsightsEvents --insight-source arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName --start-time --end-time ``` `--start-time ` specifies, in UTC, that only Insights 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. `--end-time ` specifies, in UTC, that only Insights 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. The default start time is the earliest date that data is available within the last 90 days. The default end time is the time of the event that occurred closest to the current time. All timestamps are shown in UTC. ## Looking up Insights events for management events by attribute To filter by an attribute, type the following command. ``` aws cloudtrail lookup-events --event-category insight --lookup-attributes AttributeKey=,AttributeValue= ``` You can specify only one attribute key-value pair for each **lookup-events** command. The following are valid Insights event values for `AttributeKey`. Value names are case sensitive. + `EventId` + `EventName` + `EventSource` The maximum length for the `AttributeValue` is 2000 characters. The following characters ('`_`', '` `', '`,`', '`\\n`') count as two characters towards the 2000 character limit. ### Attribute lookup examples The following example command returns Insights events in which the value of `EventName` is `PutRule`. ``` aws cloudtrail lookup-events --event-category insight --lookup-attributes AttributeKey=EventName, AttributeValue=PutRule ``` The following example command returns Insights events in which the value of `EventId` is `b5cc8c40-12ba-4d08-a8d9-2bceb9a3e002`. ``` aws cloudtrail lookup-events --event-category insight --lookup-attributes AttributeKey=EventId, AttributeValue=b5cc8c40-12ba-4d08-a8d9-2bceb9a3e002 ``` The following example command returns Insights events in which the value of `EventSource` is `iam.amazonaws.com`. ``` aws cloudtrail lookup-events --event-category insight --lookup-attributes AttributeKey=EventSource, AttributeValue=iam.amazonaws.com ``` ## Looking up Insights events for data events by dimension To filter by a dimension, type the following command. ``` aws cloudtrail list-insights-data --data-type InsightsEvents --insight-source arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName --dimensions = ``` You can specify only one dimension key-value pair for each **list-insights-events** command. The following are valid Insights event values for `DimensionKey`. Value names are case sensitive. + `EventId` + `EventName` + `EventSource` The maximum length for the `DimensionValue` is 2000 characters. The following characters ('`_`', '` `', '`,`', '`\\n`') count as two characters towards the 2000 character limit. ### Dimension lookup examples The following example command returns Insights events in which the value of `EventName` is `PutObject`. ``` aws cloudtrail list-insights-data --data-type InsightsEvents --insight-source arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName --dimensions EventName=PutObject ``` The following example command returns Insights events in which the value of `EventId` is `b5cc8c40-12ba-4d08-a8d9-2bceb9a3e002`. ``` aws cloudtrail list-insights-data --data-type InsightsEvents --insight-source arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName --dimensions EventId=b5cc8c40-12ba-4d08-a8d9-2bceb9a3e002 ``` The following example command returns Insights events in which the value of `EventSource` is `s3.amazonaws.com`. ``` aws cloudtrail list-insights-data --data-type InsightsEvents --insight-source arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName --dimensions EventSource=s3.amazonaws.com ``` ## Specifying the next page of results for Insights events for management events To get the next page of results from a `lookup-events` command, type the following command. ``` aws cloudtrail lookup-events --event-category insight --next-token= ``` In this command, the value for ** is taken from the first field of the output of the previous command. When you use `--next-token` in a command, you must use the same parameters as in the previous command. For example, suppose you run the following command. ``` aws cloudtrail lookup-events --event-category insight --lookup-attributes AttributeKey=EventName, AttributeValue=PutRule ``` To get the next page of results, your next command would look like the following. ``` aws cloudtrail lookup-events --event-category insight --lookup-attributes AttributeKey=EventName,AttributeValue=PutRule --next-token=EXAMPLEZe++mErCebpy2TgaMgmDvF1kYGFcH64JSjIbZFjsuvrSqg66b5YGssKutDYIyII4lrP4IDbeQdiObkp9YAlju3oXd12juEXAMPLE= ``` ## Specifying the next page of results for Insights events for management events To get the next page of results from a `list-insights-data` command, type the following command. ``` aws cloudtrail list-insights-data --data-type InsightsEvents --insight-source arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName --next-token= ``` In this command, the value for ** is taken from the first field of the output of the previous command. When you use `--next-token` in a command, you must use the same parameters as in the previous command. For example, suppose you run the following command. ``` aws cloudtrail list-insights-data --data-type InsightsEvents --insight-source arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName --dimensions EventName=PutObject ``` To get the next page of results, your next command would look like the following. ``` aws cloudtrail list-insights-data --data-type InsightsEvents --insight-source arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName --dimensions EventName=PutObject --next-token=EXAMPLEZe++mErCebpy2TgaMgmDvF1kYGFcH64JSjIbZFjsuvrSqg66b5YGssKutDYIyII4lrP4IDbeQdiObkp9YAlju3oXd12juEXAMPLE= ``` ## Getting JSON input from a file for Insights events for management events The AWS CLI for some AWS services has two parameters, `--generate-cli-skeleton` and `--cli-input-json`, that you can use to generate a JSON template, which you can modify and use as input to the `--cli-input-json` parameter. This section describes how to use these parameters with `aws cloudtrail lookup-events`. For more information, see [AWS CLI skeletons and input files](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-skeleton.html). **To look up Insights events by getting JSON input from a file** 1. Create an input template for use with `lookup-events` by redirecting the `--generate-cli-skeleton` output to a file, as in the following example. ``` aws cloudtrail lookup-events --event-category insight --generate-cli-skeleton > LookupEvents.txt ``` The template file generated (in this case, LookupEvents.txt) looks like the following. ``` { "LookupAttributes": [ { "AttributeKey": "", "AttributeValue": "" } ], "StartTime": null, "EndTime": null, "MaxResults": 0, "NextToken": "" } ``` 1. Use a text editor to modify the JSON as needed. The JSON input must contain only values that are specified. **Important** All empty or null values must be removed from the template before you can use it. The following example specifies a time range and maximum number of results to return. ``` { "StartTime": "2023-11-01", "EndTime": "2023-12-12", "MaxResults": 10 } ``` 1. To use the edited file as input, use the syntax `--cli-input-json file://`**, as in the following example. ``` aws cloudtrail lookup-events --event-category insight --cli-input-json file://LookupEvents.txt ``` **Note** You can use other arguments on the same command line as `--cli-input-json`. ## Getting JSON input from a file for Insights events for data events The AWS CLI for some AWS services has two parameters, `--generate-cli-skeleton` and `--cli-input-json`, that you can use to generate a JSON template, which you can modify and use as input to the `--cli-input-json` parameter. This section describes how to use these parameters with `aws cloudtrail list-insights-data`. For more information, see [AWS CLI skeletons and input files](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-skeleton.html). **To look up Insights events by getting JSON input from a file** 1. Create an input template for use with `list-insights-data` by redirecting the `--generate-cli-skeleton` output to a file, as in the following example. ``` aws cloudtrail list-insights-data --data-type InsightsEvents --generate-cli-skeleton > ListInsightsData.txt ``` The template file generated (in this case, ListInsightsData.txt) looks like the following. ``` { "InsightSource": "", "DataType": "InsightsEvents", "Dimensions": { "KeyName": "" }, "StartTime": null, "EndTime": null, "MaxResults": 0, "NextToken": "" } ``` 1. Use a text editor to modify the JSON as needed. The JSON input must contain only values that are specified. **Important** All empty or null values must be removed from the template before you can use it. The following example specifies a time range and maximum number of results to return. ``` { "InsightSource": "arn:aws:cloudtrail:us-east-2:123456789012:trail/TrailName", "DataType": "InsightsEvents", "Dimensions": { "EventName": "PutObject" }, "StartTime": "2025-11-01", "EndTime": "2025-11-05", "MaxResults": 1 } ``` 1. To use the edited file as input, use the syntax `--cli-input-json file://`**, as in the following example. ``` aws cloudtrail list-insights-data --data-type InsightsEvents --cli-input-json file://ListInsightsData.txt ``` **Note** You can use other arguments on the same command line as `--cli-input-json`. ## Lookup output fields **Events** A list of lookup events based on the lookup attribute and time range that were specified. The events list is sorted by time, with the latest event listed first. Each entry contains information about the lookup request and includes a string representation of the CloudTrail event that was retrieved. The following entries describe the fields in each lookup event. **CloudTrailEvent** A JSON string that contains an object representation of the event returned. For information about each of the elements returned, see [ Record Body Contents](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-record-contents.html). **EventId** A string that contains the GUID of the event returned. **EventName** A string that contains the name of the event returned. **EventSource** The AWS service that the request was made to. **EventTime** The date and time, in UNIX time format, of the event. **Resources** A list of resources referenced by the event that was returned. Each resource entry specifies a resource type and a resource name. **ResourceName** A string that contains the name of the resource referenced by the event. **ResourceType** A string that contains the type of a resource referenced by the event. When the resource type cannot be determined, null is returned. **Username** A string that contains the user name of the account for the event returned. **NextToken** A string to get the next page of results from a previous `lookup-events` command. To use the token, the parameters must be the same as those in the original command. If no `NextToken` entry appears in the output, there are no more results to return. For more information about CloudTrail Insights events, see [Working with CloudTrail Insights](logging-insights-events-with-cloudtrail.md) in this guide. # Viewing Insights events for event data stores This section describes how you can view Insights events for an Insights event data store by viewing the **Insights events dashboard** and running sample queries. For information about how to enable CloudTrail Insights on an event data store, see [Enabling CloudTrail Insights on an existing event data store with the console](insights-events-enable.md#insights-events-enable-lake). CloudTrail queries incur charges based upon the amount of data scanned. To help control costs, we recommend that you constrain queries by adding starting and ending `eventTime` time stamps to queries. For more information about CloudTrail pricing, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/). For descriptions of Insights events record fields for event data stores, see [CloudTrail record contents for Insights events for event data stores](cloudtrail-insights-fields-lake.md). **Topics** + [ ## Viewing the Insights dashboard for an event data store ](#insights-events-view-lake-dashboard) + [ ## Viewing sample queries for Insights events ](#insights-events-lake-queries) ## Viewing the Insights dashboard for an event data store The **Insights events dashboard** shows the overall proportion of Insights events by Insights type, the proportion of Insights events by Insights type for the top users and services, and the number of Insights events per day. The dashboard also includes a widget that lists up to 30 days of Insights events. **Note** After you enable CloudTrail Insights for the first time on the source event data store, CloudTrail may take up to 7 days to begin delivering Insights events, provided that unusual activity is detected during that time. For more information, see [Delivery of Insights events](insights-events-understanding.md). The **Insights events dashboard** only displays information about the Insights events collected by the selected event data store, which is determined by the configuration of the source event data store. For example, if you configure the source event data store to enable Insights events on `ApiCallRateInsight` but not `ApiErrorRateInsight`, you won't see information about Insights events on `ApiErrorRateInsight`. **To view the Insights events dashboard** 1. Sign in to the AWS Management Console and open the CloudTrail console at [https://console.aws.amazon.com/cloudtrail/](https://console.aws.amazon.com/cloudtrail/). 1. In the left navigation pane, under **Lake**, choose **Dashboard**. 1. Choose the **Managed and custom dashboards** tab. 1. From **AWS managed dashboards**, choose **Insights events dashboard**. 1. Choose your Insights event data store. 1. Choose to filter the dashboard data by an **Absolute range** or **Relative range**. Choose **Absolute range** to select a specific date and time range. Choose **Relative range** to select a predefined time range or a custom range. By default, the dashboard displays event data for the past 24 hours. **Note** CloudTrail Lake queries incur costs based upon the amount of data scanned. To help control costs, you can filter on a narrower time range. For more information about CloudTrail pricing, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/). 1. Choose the refresh icon to populate the graphics for the dashboard's widgets. Each widget indicates the status of the refresh. For more information about Lake dashboards, see [CloudTrail Lake dashboards](lake-dashboard.md). ## Viewing sample queries for Insights events The CloudTrail console provides a number of sample queries for Insights events that can help you get started writing your own queries. **To view sample queries for Insights events** 1. Sign in to the AWS Management Console and open the CloudTrail console at [https://console.aws.amazon.com/cloudtrail/](https://console.aws.amazon.com/cloudtrail/). 1. From the navigation pane, under **Lake**, choose **Query**. 1. On the **Query** page, choose the **Sample queries** tab. 1. Search for queries for Insights events. Choose the **Query name** to open the query in the **Editor** tab. ![\[Example shows sample queries for Insights events\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/images/ct-insights-sample-queries.png) 1. On the **Editor** tab, choose the Insights event data store. When you choose the event data store from the list, CloudTrail automatically populates the event data store ID in the `FROM` line of the query editor. 1. Choose **Run** to run the query. After the query completes, you can view the command output and query results. The **Command output** tab shows you metadata about your query, such as whether the query was successful, the number of records matched, and the run time of the query. The **Query results** tab shows you the event data in the selected event data store that matched your query. For more information about editing a query, see [Create or edit a query with the CloudTrail console](query-create-edit-query.md). For more information about running a query and saving query results, see [Run a query and save query results with the console](query-run-query.md).