Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Viewing recent management events with the Amazon CLI

You can look up CloudTrail management events for the last 90 days for the current Amazon Web Services Region using the aws cloudtrail lookup-events command. The aws cloudtrail lookup-events command shows events in the Amazon Web Services Region where they occurred.

Lookup supports the following attributes for management events:

All attributes are optional.

The lookup-events command includes the following options:

For general information about using the Amazon Command Line Interface, see the Amazon Command Line Interface User Guide.

Prerequisites

Getting command line help

To see the command line help for lookup-events, type the following command:

aws cloudtrail lookup-events help

Looking up events

To see the ten latest events, type the following command:

aws cloudtrail lookup-events --max-items 10

A returned event looks similar to the following fictitious example, which has been formatted for readability:

{
    "NextToken": "kbOt5LlZe++mErCebpy2TgaMgmDvF1kYGFcH64JSjIbZFjsuvrSqg66b5YGssKutDYIyII4lrP4IDbeQdiObkp9YAlju3oXd12juy3CIZW8=", 
    "Events": [
        {
            "EventId": "0ebbaee4-6e67-431d-8225-ba0d81df5972", 
            "Username": "root", 
            "EventTime": 1424476529.0, 
            "CloudTrailEvent": "{
                  \"eventVersion\":\"1.02\",
                  \"userIdentity\":{
                        \"type\":\"Root\",
                        \"principalId\":\"111122223333\",
                        \"arn\":\"arn:aws:iam::111122223333:root\",
                        \"accountId\":\"111122223333\"},
                  \"eventTime\":\"2015-02-20T23:55:29Z\",
                  \"eventSource\":\"signin.amazonaws.com\",
                  \"eventName\":\"ConsoleLogin\",
                  \"awsRegion\":\"us-east-2\",
                  \"sourceIPAddress\":\"203.0.113.4\",
                  \"userAgent\":\"Mozilla/5.0\",
                  \"requestParameters\":null,
                  \"responseElements\":{\"ConsoleLogin\":\"Success\"},
                  \"additionalEventData\":{
                         \"MobileVersion\":\"No\",
                         \"LoginTo\":\"https://console.aws.amazon.com/console/home",
                         \"MFAUsed\":\"No\"},
                  \"eventID\":\"0ebbaee4-6e67-431d-8225-ba0d81df5972\",
                  \"eventType\":\"AwsApiCall\",
                  \"recipientAccountId\":\"111122223333\"}", 
            "EventName": "ConsoleLogin", 
            "Resources": []
        }
    ]
}        

For an explanation of the lookup-related fields in the output, see the section Lookup output fields later in this document. For an explanation of the fields in the CloudTrail event, see CloudTrail record contents.

Specifying the number of events to return

To specify the number of events to return, type the following command:

aws cloudtrail lookup-events --max-items <integer>

Possible values are 1 through 50. The following example returns one event.

aws cloudtrail lookup-events --max-items 1

Looking up events by time range

Events from the past 90 days are available for lookup. To specify a time range, type the following command:

aws cloudtrail lookup-events --start-time <timestamp> --end-time <timestamp>

--start-time <timestamp> specifies, in UTC, 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.

--end-time <timestamp> specifies, in UTC, 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.

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 events by attribute

To filter by an attribute, type the following command:

aws cloudtrail lookup-events --lookup-attributes AttributeKey=<attribute>,AttributeValue=<string>

You can specify only one attribute key/value pair for each lookup-events command. The following are valid values for AttributeKey. Value names are case sensitive.

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 events in Region cn-northwest-1, which allows you to view global service events. Replace gseService with the appropriate value for your configuration.

aws cloudtrail --region cn-northwest-1  lookup-events --lookup-attributes AttributeKey=EventName,AttributeValue=gseService

The following example command returns events in which the value of AccessKeyId is AKIAIOSFODNN7EXAMPLE.

aws cloudtrail lookup-events --lookup-attributes AttributeKey=AccessKeyId,AttributeValue=AKIAIOSFODNN7EXAMPLE

The following example command returns the event for the specified CloudTrail EventId.

aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventId,AttributeValue=b5cc8c40-12ba-4d08-a8d9-2bceb9a3e002

The following example command returns events in which the value of EventName is RunInstances.

aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventName,AttributeValue=RunInstances

The following example command returns events in which the value of EventSource is iam.amazonaws.com.

aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventSource,AttributeValue=iam.amazonaws.com

The following example command returns write events. It excludes read events such as GetBucketLocation and DescribeStream.

aws cloudtrail lookup-events --lookup-attributes AttributeKey=ReadOnly,AttributeValue=false

The following example command returns events in which the value of ResourceName is CloudTrail_CloudWatchLogs_Role.

aws cloudtrail lookup-events --lookup-attributes AttributeKey=ResourceName,AttributeValue=CloudTrail_CloudWatchLogs_Role

The following example command returns events in which the value of ResourceType is AWS::S3::Bucket.

aws cloudtrail lookup-events --lookup-attributes AttributeKey=ResourceType,AttributeValue=AWS::S3::Bucket

The following example command returns events in which the value of Username is root.

aws cloudtrail lookup-events --lookup-attributes AttributeKey=Username,AttributeValue=root

Specifying the next page of results

To get the next page of results from a lookup-events command, type the following command:

aws cloudtrail lookup-events <same parameters as previous command> --next-token=<token>

where the value for <token> 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 --lookup-attributes AttributeKey=Username,AttributeValue=root

To get the next page of results, your next command would look like this:

aws cloudtrail lookup-events --lookup-attributes AttributeKey=Username,AttributeValue=root --next-token=kbOt5LlZe++mErCebpy2TgaMgmDvF1kYGFcH64JSjIbZFjsuvrSqg66b5YGssKutDYIyII4lrP4IDbeQdiObkp9YAlju3oXd12juy3CIZW8=

Getting JSON input from a file

The Amazon CLI for some Amazon 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 general information, see Amazon CLI skeletons and input files.

Lookup output fields