AWS CloudTrail

(1)

AWS CloudTrail

API Reference

API Version 2013-11-01

(2)

AWS CloudTrail: API Reference

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

Welcome

This is the CloudTrail API Reference. It provides descriptions of actions, data types, common parameters, and common errors for CloudTrail.

CloudTrail is a web service that records AWS API calls for your AWS account and delivers log ﬁles to an Amazon S3 bucket. The recorded information includes the identity of the user, the start time of the AWS API call, the source IP address, the request parameters, and the response elements returned by the service.

Note

As an alternative to the API, you can use one of the AWS SDKs, which consist of libraries and sample code for various programming languages and platforms (Java, Ruby, .NET, iOS, Android, etc.). The SDKs provide programmatic access to AWS CloudTrail. For example, the SDKs handle cryptographically signing requests, managing errors, and retrying requests automatically. For more information about the AWS SDKs, including how to download and install them, see Tools to Build on AWS.

See the AWS CloudTrail User Guide for information about the data that is included with each AWS API call listed in the log ﬁles.

This document was last published on March 6, 2022.

(9)

Actions

The following actions are supported:

• AddTags (p. 3)

• CancelQuery (p. 6)

• CreateEventDataStore (p. 9)

• CreateTrail (p. 15)

• DeleteEventDataStore (p. 23)

• DeleteTrail (p. 25)

• DescribeQuery (p. 27)

• DescribeTrails (p. 30)

• GetEventDataStore (p. 33)

• GetEventSelectors (p. 37)

• GetInsightSelectors (p. 40)

• GetQueryResults (p. 43)

• GetTrail (p. 47)

• GetTrailStatus (p. 49)

• ListEventDataStores (p. 53)

• ListPublicKeys (p. 56)

• ListQueries (p. 59)

• ListTags (p. 63)

• ListTrails (p. 66)

• LookupEvents (p. 68)

• PutEventSelectors (p. 72)

• PutInsightSelectors (p. 77)

• RemoveTags (p. 81)

• RestoreEventDataStore (p. 84)

• StartLogging (p. 88)

• StartQuery (p. 90)

• StopLogging (p. 93)

• UpdateEventDataStore (p. 95)

• UpdateTrail (p. 101)

(10)

AddTags

Adds one or more tags to a trail, up to a limit of 50. Overwrites an existing tag's value when a new value is specified for an existing tag key. Tag key names must be unique for a trail; you cannot have two keys with the same name but different values. If you specify a key without a value, the tag will be created with the specified key and a value of null. You can tag a trail that applies to all AWS Regions only from the Region in which the trail was created (also known as its home region).

Request Syntax

{

"ResourceId": "string", "TagsList": [

{

"Key": "string", "Value": "string"

} ] }

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters (p. 136).

The request accepts the following data in JSON format.

ResourceId (p. 3)

Speciﬁes the ARN of the trail to which one or more tags will be added. The format of a trail ARN is:

arn:aws:cloudtrail:us-east-2:123456789012:trail/MyTrail Type: String

Required: Yes TagsList (p. 3)

Contains a list of tags, up to a limit of 50 Type: Array of Tag (p. 131) objects

Array Members: Maximum number of 200 items.

Required: Yes

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors (p. 138).

(11)

Errors

CloudTrailARNInvalidException

This exception is thrown when an operation is called with a trail ARN that is not valid. The following is the format of a trail ARN.

arn:aws:cloudtrail:us-east-2:123456789012:trail/MyTrail HTTP Status Code: 400

ConﬂictException

This exception is thrown when the speciﬁed resource is not ready for an operation. This can occur when you try to run an operation on a trail before CloudTrail has time to fully load the trail. If this exception occurs, wait a few minutes, and then try the operation again.

HTTP Status Code: 400

EventDataStoreNotFoundException

The speciﬁed event data store was not found.

HTTP Status Code: 400 InactiveEventDataStoreException

The event data store against which you ran your query is inactive.

HTTP Status Code: 400 InvalidTagParameterException

This exception is thrown when the speciﬁed tag key or values are not valid. It can also occur if there are duplicate tags or too many tags on the resource.

HTTP Status Code: 400 InvalidTrailNameException

This exception is thrown when the provided trail name is not valid. Trail names 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) HTTP Status Code: 400

NotOrganizationMasterAccountException

This exception is thrown when the AWS account making the request to create or update an organization trail is not the management account for an organization in AWS Organizations. For more information, see Prepare For Creating a Trail For Your Organization.

HTTP Status Code: 400 OperationNotPermittedException

This exception is thrown when the requested operation is not permitted.

HTTP Status Code: 400 ResourceNotFoundException

This exception is thrown when the speciﬁed resource is not found.

(12)

See Also

ResourceTypeNotSupportedException

This exception is thrown when the speciﬁed resource type is not supported by CloudTrail.

HTTP Status Code: 400 TagsLimitExceededException

The number of tags per trail has exceeded the permitted amount. Currently, the limit is 50.

HTTP Status Code: 400 UnsupportedOperationException

This exception is thrown when the requested operation is not supported.

CancelQuery

Cancels a query if the query is not in a terminated state, such as CANCELLED, FAILED or FINISHED. You must specify an ARN value for EventDataStore. The ID of the query that you want to cancel is also required. When you run CancelQuery, the query status might show as CANCELLED even if the operation is not yet ﬁnished.

Request Syntax

{

"EventDataStore": "string", "QueryId": "string"

}

Request Parameters

EventDataStore (p. 6)

The ARN (or the ID suﬃx of the ARN) of an event data store on which the speciﬁed query is running.

Type: String

Length Constraints: Minimum length of 3. Maximum length of 256.

Pattern: ^[a-zA-Z0-9._/\-:]+$

Required: Yes QueryId (p. 6)

The ID of the query that you want to cancel. The QueryId comes from the response of a StartQuery operation.

Type: String

Length Constraints: Fixed length of 36.

Pattern: ^[a-f0-9\-]+$

Required: Yes

Response Syntax

{

"QueryId": "string", "QueryStatus": "string"

}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

(14)

Errors

The following data is returned in JSON format by the service.

QueryId (p. 6)

The ID of the canceled query.

Type: String

QueryStatus (p. 6)

Shows the status of a query after a CancelQuery request. Typically, the values shown are either RUNNING or CANCELLED.

Type: String

Valid Values: QUEUED | RUNNING | FINISHED | FAILED | CANCELLED

Errors

EventDataStoreARNInvalidException

The speciﬁed event data store ARN is not valid or does not map to an event data store in your account.

HTTP Status Code: 400 InactiveQueryException

The speciﬁed query cannot be canceled because it is in the FINISHED, FAILED, or CANCELLED state.

HTTP Status Code: 400 InvalidParameterException

The request includes a parameter that is not valid.

(15)

See Also

OperationNotPermittedException

HTTP Status Code: 400 QueryIdNotFoundException

The query ID does not exist or does not map to a query.

CreateEventDataStore

Creates a new event data store.

Request Syntax

{ "AdvancedEventSelectors": [ {

"FieldSelectors": [ {

"EndsWith": [ "string" ], "Equals": [ "string" ], "Field": "string",

"NotEndsWith": [ "string" ], "NotEquals": [ "string" ], "NotStartsWith": [ "string" ], "StartsWith": [ "string" ] }

],

"Name": "string"

} ],

"MultiRegionEnabled": boolean, "Name": "string",

"OrganizationEnabled": boolean, "RetentionPeriod": number, "TagsList": [

{

} ],

"TerminationProtectionEnabled": boolean }

Request Parameters

AdvancedEventSelectors (p. 9)

The advanced event selectors to use to select the events for the data store. For more information about how to use advanced event selectors, see Log events by using advanced event selectors in the CloudTrail User Guide.

Type: Array of AdvancedEventSelector (p. 110) objects Required: No

MultiRegionEnabled (p. 9)

Speciﬁes whether the event data store includes events from all regions, or only from the region in which the event data store is created.

Type: Boolean

(17)

Response Syntax

Required: No Name (p. 9)

The name of the event data store.

Type: String

Pattern: ^[a-zA-Z0-9._\-]+$

Required: Yes

OrganizationEnabled (p. 9)

Speciﬁes whether an event data store collects events logged for an organization in AWS Organizations.

Type: Boolean Required: No RetentionPeriod (p. 9)

The retention period of the event data store, in days. You can set a retention period of up to 2555 days, the equivalent of seven years.

Type: Integer

Valid Range: Minimum value of 7. Maximum value of 2555.

Required: No TagsList (p. 9)

A list of tags.

Type: Array of Tag (p. 131) objects

Required: No

TerminationProtectionEnabled (p. 9)

Speciﬁes whether termination protection is enabled for the event data store. If termination protection is enabled, you cannot delete the event data store until termination protection is disabled.

Type: Boolean Required: No

Response Syntax

"EndsWith": [ "string" ], "Equals": [ "string" ],

(18)

Response Elements

"Field": "string",

],

"Name": "string"

} ],

"CreatedTimestamp": number, "EventDataStoreArn": "string", "MultiRegionEnabled": boolean, "Name": "string",

"OrganizationEnabled": boolean, "RetentionPeriod": number, "Status": "string",

"TagsList": [ {

} ],

"TerminationProtectionEnabled": boolean, "UpdatedTimestamp": number

}

Response Elements

The advanced event selectors that were used to select the events for the data store.

Type: Array of AdvancedEventSelector (p. 110) objects CreatedTimestamp (p. 10)

The timestamp that shows when the event data store was created.

Type: Timestamp EventDataStoreArn (p. 10)

The ARN of the event data store.

Type: String

Pattern: ^[a-zA-Z0-9._/\-:]+$

Indicates whether the event data store collects events from all regions, or only from the region in which it was created.

Type: Boolean Name (p. 10)

(19)

Errors

Type: String

Indicates whether an event data store is collecting logged events for an organization in AWS Organizations.

Type: Boolean RetentionPeriod (p. 10)

The retention period of an event data store, in days.

Type: Integer

Status (p. 10)

The status of event data store creation.

Type: String

Valid Values: CREATED | ENABLED | PENDING_DELETION TagsList (p. 10)

A list of tags.

TerminationProtectionEnabled (p. 10)

Indicates whether termination protection is enabled for the event data store.

Type: Boolean

UpdatedTimestamp (p. 10)

The timestamp that shows when an event data store was updated, if applicable.

UpdatedTimestamp is always either the same or newer than the time shown in CreatedTimestamp.

Type: Timestamp

Errors

CloudTrailAccessNotEnabledException

This exception is thrown when trusted access has not been enabled between AWS CloudTrail and AWS Organizations. For more information, see Enabling Trusted Access with Other AWS Services and Prepare For Creating a Trail For Your Organization.

(20)

Errors

EventDataStoreAlreadyExistsException

An event data store with that name already exists.

EventDataStoreMaxLimitExceededException

Your account has used the maximum number of event data stores.

InsuﬃcientDependencyServiceAccessPermissionException

This exception is thrown when the IAM user or role that is used to create the organization trail is lacking one or more required permissions for creating an organization trail in a required service. For more information, see Prepare For Creating a Trail For Your Organization.

OrganizationNotInAllFeaturesModeException

This exception is thrown when AWS Organizations is not conﬁgured to support all features. All features must be enabled in Organizations to support creating an organization trail. For more information, see Prepare For Creating a Trail For Your Organization.

HTTP Status Code: 400 OrganizationsNotInUseException

This exception is thrown when the request is made from an AWS account that is not a member of an organization. To make this request, sign in using the credentials of an account that belongs to an organization.

(21)

See Also

CreateTrail

Creates a trail that speciﬁes the settings for delivery of log data to an Amazon S3 bucket.

Request Syntax

{ "CloudWatchLogsLogGroupArn": "string", "CloudWatchLogsRoleArn": "string", "EnableLogFileValidation": boolean, "IncludeGlobalServiceEvents": boolean, "IsMultiRegionTrail": boolean,

"IsOrganizationTrail": boolean, "KmsKeyId": "string",

"Name": "string",

"S3BucketName": "string", "S3KeyPrefix": "string", "SnsTopicName": "string", "TagsList": [

{

} ]}

Request Parameters

CloudWatchLogsLogGroupArn (p. 15)

Speciﬁes a log group name using an Amazon Resource Name (ARN), a unique identiﬁer that represents the log group to which CloudTrail logs will be delivered. Not required unless you specify CloudWatchLogsRoleArn.

Type: String Required: No

CloudWatchLogsRoleArn (p. 15)

Speciﬁes the role for the CloudWatch Logs endpoint to assume to write to a user's log group.

Type: String Required: No

EnableLogFileValidation (p. 15)

Speciﬁes whether log ﬁle integrity validation is enabled. The default is false.

NoteWhen you disable log file integrity validation, the chain of digest files is broken after one hour. CloudTrail does not create digest files for log files that were delivered during a period in which log file integrity validation was disabled. For example, if you enable log file integrity validation at noon on January 1, disable it at noon on January 2, and re-enable

(23)

Request Parameters

it at noon on January 10, digest ﬁles will not be created for the log ﬁles delivered from noon on January 2 to noon on January 10. The same applies whenever you stop CloudTrail logging or delete a trail.

IncludeGlobalServiceEvents (p. 15)

Speciﬁes whether the trail is publishing events from global services such as IAM to the log ﬁles.

IsMultiRegionTrail (p. 15)

Speciﬁes whether the trail is created in the current region or in all regions. The default is false, which creates a trail only in the region where you are signed in. As a best practice, consider creating trails that log events in all regions.

IsOrganizationTrail (p. 15)

Speciﬁes whether the trail is created for all accounts in an organization in AWS Organizations, or only for the current AWS account. The default is false, and cannot be true unless the call is made on behalf of an AWS account that is the management account for an organization in AWS Organizations.

Type: Boolean Required: No KmsKeyId (p. 15)

Specifies the AWS KMS key ID to use to encrypt the logs delivered by CloudTrail. The value can be an alias name prefixed by "alias/", a fully specified ARN to an alias, a fully specified ARN to a key, or a globally unique identifier.

CloudTrail also supports AWS KMS multi-Region keys. For more information about multi-Region keys, see Using multi-Region keys in the AWS Key Management Service Developer Guide.

Examples:

• alias/MyAliasName

• arn:aws:kms:us-east-2:123456789012:alias/MyAliasName

• arn:aws:kms:us-east-2:123456789012:key/12345678-1234-1234-1234-123456789012

• 12345678-1234-1234-1234-123456789012 Type: String

Required: No Name (p. 15)

Speciﬁes the name of the trail. The name must meet the following requirements:

(24)

Response Syntax

• Not be in IP address format (for example, 192.168.5.4) Type: String

Required: Yes S3BucketName (p. 15)

Speciﬁes the name of the Amazon S3 bucket designated for publishing log ﬁles. See Amazon S3 Bucket Naming Requirements.

Type: String Required: Yes S3KeyPreﬁx (p. 15)

Specifies the Amazon S3 key prefix that comes after the name of the bucket you have designated for log file delivery. For more information, see Finding Your CloudTrail Log Files. The maximum length is 200 characters.

Type: String Required: No SnsTopicName (p. 15)

Specifies the name of the Amazon SNS topic defined for notification of log file delivery. The maximum length is 256 characters.

Type: String Required: No TagsList (p. 15)

A list of tags.

Required: No

Response Syntax

{ "CloudWatchLogsLogGroupArn": "string", "CloudWatchLogsRoleArn": "string", "IncludeGlobalServiceEvents": boolean, "IsMultiRegionTrail": boolean,

"LogFileValidationEnabled": boolean, "Name": "string",

"S3BucketName": "string", "S3KeyPrefix": "string", "SnsTopicARN": "string", "SnsTopicName": "string", "TrailARN": "string"

(25)

Response Elements

}

Response Elements

CloudWatchLogsLogGroupArn (p. 17)

Speciﬁes the Amazon Resource Name (ARN) of the log group to which CloudTrail logs will be delivered.

Type: String

CloudWatchLogsRoleArn (p. 17)

Speciﬁes the role for the CloudWatch Logs endpoint to assume to write to a user's log group.

Type: String

IncludeGlobalServiceEvents (p. 17)

Speciﬁes whether the trail is publishing events from global services such as IAM to the log ﬁles.

Type: Boolean IsMultiRegionTrail (p. 17)

Speciﬁes whether the trail exists in one region or in all regions.

Type: Boolean

IsOrganizationTrail (p. 17)

Speciﬁes whether the trail is an organization trail.

Type: Boolean KmsKeyId (p. 17)

Speciﬁes the AWS KMS key ID that encrypts the logs delivered by CloudTrail. The value is a fully speciﬁed ARN to a AWS KMS key in the following format.

arn:aws:kms:us-east-2:123456789012:key/12345678-1234-1234-1234-123456789012 Type: String

LogFileValidationEnabled (p. 17)

Speciﬁes whether log ﬁle integrity validation is enabled.

Speciﬁes the name of the trail.

Type: String S3BucketName (p. 17)

Speciﬁes the name of the Amazon S3 bucket designated for publishing log ﬁles.

Type: String

(26)

Errors

S3KeyPreﬁx (p. 17)

Specifies the Amazon S3 key prefix that comes after the name of the bucket you have designated for log file delivery. For more information, see Finding Your CloudTrail Log Files.

Type: String SnsTopicARN (p. 17)

Specifies the ARN of the Amazon SNS topic that CloudTrail uses to send notifications when log files are delivered. The format of a topic ARN is:

arn:aws:sns:us-east-2:123456789012:MyTopic Type: String

SnsTopicName (p. 17)

This parameter has been deprecated.

This ﬁeld is no longer in use. Use CreateTrail:SnsTopicARN (p. 19).

Type: String TrailARN (p. 17)

Speciﬁes the ARN of the trail that was created. The format of a trail ARN is:

Errors

CloudTrailAccessNotEnabledException

This exception is thrown when trusted access has not been enabled between AWS CloudTrail and AWS Organizations. For more information, see Enabling Trusted Access with Other AWS Services and Prepare For Creating a Trail For Your Organization.

CloudTrailInvalidClientTokenIdException

This exception is thrown when a call results in the InvalidClientTokenId error code. This can occur when you are creating or updating a trail to send notiﬁcations to an Amazon SNS topic that is in a suspended AWS account.

CloudWatchLogsDeliveryUnavailableException

Cannot set a CloudWatch Logs delivery for this region.

HTTP Status Code: 400 ConﬂictException

(27)

Errors

InsuﬃcientEncryptionPolicyException

This exception is thrown when the policy on the S3 bucket or AWS KMS key is not suﬃcient.

InsuﬃcientS3BucketPolicyException

This exception is thrown when the policy on the S3 bucket is not suﬃcient.

InsuﬃcientSnsTopicPolicyException

This exception is thrown when the policy on the Amazon SNS topic is not suﬃcient.

InvalidCloudWatchLogsLogGroupArnException

This exception is thrown when the provided CloudWatch Logs log group is not valid.

InvalidCloudWatchLogsRoleArnException

This exception is thrown when the provided role is not valid.

HTTP Status Code: 400 InvalidKmsKeyIdException

This exception is thrown when the AWS KMS key ARN is not valid.

InvalidParameterCombinationException

This exception is thrown when the combination of parameters provided is not valid.

HTTP Status Code: 400 InvalidS3BucketNameException

This exception is thrown when the provided S3 bucket name is not valid.

HTTP Status Code: 400 InvalidS3PreﬁxException

This exception is thrown when the provided S3 preﬁx is not valid.

HTTP Status Code: 400 InvalidSnsTopicNameException

This exception is thrown when the provided SNS topic name is not valid.

(28)

Errors

KmsException

This exception is thrown when there is an issue with the speciﬁed AWS KMS key and the trail can’t be updated.

HTTP Status Code: 400 KmsKeyDisabledException

This error has been deprecated.

This exception is no longer in use.

HTTP Status Code: 400 KmsKeyNotFoundException

This exception is thrown when the AWS KMS key does not exist, when the S3 bucket and the AWS KMS key are not in the same region, or when the AWS KMS key associated with the Amazon SNS topic either does not exist or is not in the same region.

MaximumNumberOfTrailsExceededException

This exception is thrown when the maximum number of trails is reached.

(29)

See Also

OrganizationNotInAllFeaturesModeException

This exception is thrown when AWS Organizations is not conﬁgured to support all features. All features must be enabled in Organizations to support creating an organization trail. For more information, see Prepare For Creating a Trail For Your Organization.

HTTP Status Code: 400 OrganizationsNotInUseException

This exception is thrown when the request is made from an AWS account that is not a member of an organization. To make this request, sign in using the credentials of an account that belongs to an organization.

HTTP Status Code: 400 S3BucketDoesNotExistException

This exception is thrown when the speciﬁed S3 bucket does not exist.

HTTP Status Code: 400 TrailAlreadyExistsException

This exception is thrown when the speciﬁed trail already exists.

HTTP Status Code: 400 TrailNotProvidedException

This exception is no longer in use.

DeleteEventDataStore

Disables the event data store speciﬁed by EventDataStore, which accepts an event data store ARN.

After you run DeleteEventDataStore, the event data store enters a PENDING_DELETION state, and is automatically deleted after a wait period of seven days. TerminationProtectionEnabled must be set to False on the event data store; this operation cannot work if TerminationProtectionEnabled is True.

After you run DeleteEventDataStore on an event data store, you cannot run ListQueries, DescribeQuery, or GetQueryResults on queries that are using an event data store in a

PENDING_DELETION state. An event data store in the PENDING_DELETION state does not incur costs.

Request Syntax

{ "EventDataStore": "string"

}

Request Parameters

The ARN (or the ID suﬃx of the ARN) of the event data store to delete.

Type: String

Pattern: ^[a-zA-Z0-9._/\-:]+$

Required: Yes

Response Elements

Errors

(31)

See Also

EventDataStoreTerminationProtectedException

The event data store cannot be deleted because termination protection is enabled for it.

DeleteTrail

Deletes a trail. This operation must be called from the region in which the trail was created.

DeleteTrail cannot be called on the shadow trails (replicated trails in other regions) of a trail that is enabled in all regions.

Request Syntax

{

"Name": "string"

}

Request Parameters

Name (p. 25)

Speciﬁes the name or the CloudTrail ARN of the trail to be deleted. The following is the format of a trail ARN. arn:aws:cloudtrail:us-east-2:123456789012:trail/MyTrail

Type: String Required: Yes

Response Elements

Errors

HTTP Status Code: 400 InvalidHomeRegionException

This exception is thrown when an operation is called on a trail from a region other than the region in which the trail was created.

(33)

See Also

HTTP Status Code: 400 TrailNotFoundException

This exception is thrown when the trail with the given name is not found.

DescribeQuery

Returns metadata about a query, including query run time in milliseconds, number of events scanned and matched, and query status. You must specify an ARN for EventDataStore, and a value for QueryID.

Request Syntax

{ "EventDataStore": "string", "QueryId": "string"

}

Request Parameters

The ARN (or the ID suﬃx of the ARN) of an event data store on which the speciﬁed query was run.

Type: String

Pattern: ^[a-zA-Z0-9._/\-:]+$

Required: Yes QueryId (p. 27)

The query ID.

Type: String

Required: Yes

Response Syntax

{

"ErrorMessage": "string", "QueryId": "string", "QueryStatistics": { "CreationTime": number, "EventsMatched": number, "EventsScanned": number, "ExecutionTimeInMillis": number },

"QueryStatus": "string", "QueryString": "string"

(35)

Response Elements

}

Response Elements

ErrorMessage (p. 27)

The error message returned if a query failed.

Type: String

Pattern: .*

QueryId (p. 27)

The ID of the query.

Type: String

QueryStatistics (p. 27)

Metadata about a query, including the number of events that were matched, the total number of events scanned, the query run time in milliseconds, and the query's creation time.

Type: QueryStatisticsForDescribeQuery (p. 128) object QueryStatus (p. 27)

The status of a query. Values for QueryStatus include QUEUED, RUNNING, FINISHED, FAILED, or CANCELLED

Type: String

Valid Values: QUEUED | RUNNING | FINISHED | FAILED | CANCELLED QueryString (p. 27)

The SQL code of a query.

Type: String

Pattern: (?s).*

Errors

(36)

See Also

HTTP Status Code: 400 QueryIdNotFoundException

The query ID does not exist or does not map to a query.

DescribeTrails

Retrieves settings for one or more trails associated with the current region for your account.

Request Syntax

{ "includeShadowTrails": boolean, "trailNameList": [ "string" ] }

Request Parameters

includeShadowTrails (p. 30)

Speciﬁes whether to include shadow trails in the response. A shadow trail is the replication in a region of a trail that was created in a diﬀerent region, or in the case of an organization trail, the replication of an organization trail in member accounts. If you do not include shadow trails, organization trails in a member account and region replication trails will not be returned. The default is true.

Type: Boolean Required: No trailNameList (p. 30)

Speciﬁes a list of trail names, trail ARNs, or both, of the trails to describe. The format of a trail ARN is:

arn:aws:cloudtrail:us-east-2:123456789012:trail/MyTrail

If an empty list is speciﬁed, information for the trail in the current region is returned.

• If an empty list is speciﬁed and IncludeShadowTrails is false, then information for all trails in the current region is returned.

• If an empty list is speciﬁed and IncludeShadowTrails is null or true, then information for all trails in the current region and any associated shadow trails in other regions is returned.

NoteIf one or more trail names are speciﬁed, information is returned only if the names match the names of trails belonging only to the current region. To return information about a trail in another region, you must specify its trail ARN.

Type: Array of strings Required: No

Response Syntax

{ "trailList": [

(38)

Response Elements

{

"CloudWatchLogsLogGroupArn": "string", "CloudWatchLogsRoleArn": "string", "HasCustomEventSelectors": boolean, "HasInsightSelectors": boolean, "HomeRegion": "string",

"IncludeGlobalServiceEvents": boolean, "IsMultiRegionTrail": boolean,

"LogFileValidationEnabled": boolean, "Name": "string",

"S3BucketName": "string", "S3KeyPrefix": "string", "SnsTopicARN": "string", "SnsTopicName": "string", "TrailARN": "string"

} ] }

Response Elements

trailList (p. 30)

The list of trail objects. Trail objects with string values are only returned if values for the objects exist in a trail's configuration. For example, SNSTopicName and SNSTopicARN are only returned in results if a trail is configured to send SNS notifications. Similarly, KMSKeyId only appears in results if a trail's log files are encrypted with AWS KMS customer managed keys.

Type: Array of Trail (p. 132) objects

Errors

InvalidTrailNameException

(39)

See Also

UnsupportedOperationException

GetEventDataStore

Returns information about an event data store speciﬁed as either an ARN or the ID portion of the ARN.

Request Syntax

{

"EventDataStore": "string"

}

Request Parameters

The ARN (or ID suﬃx of the ARN) of the event data store about which you want information.

Type: String

Pattern: ^[a-zA-Z0-9._/\-:]+$

Required: Yes

Response Syntax

{

"AdvancedEventSelectors": [ {

],

"Name": "string"

} ],

"CreatedTimestamp": number, "EventDataStoreArn": "string", "MultiRegionEnabled": boolean, "Name": "string",

"OrganizationEnabled": boolean, "RetentionPeriod": number, "Status": "string",

"TerminationProtectionEnabled": boolean, "UpdatedTimestamp": number

(41)

Response Elements

}

Response Elements

The advanced event selectors used to select events for the data store.

Type: Array of AdvancedEventSelector (p. 110) objects CreatedTimestamp (p. 33)

The timestamp of the event data store's creation.

Type: Timestamp EventDataStoreArn (p. 33)

The event data store Amazon Resource Number (ARN).

Type: String

Pattern: ^[a-zA-Z0-9._/\-:]+$

Indicates whether the event data store includes events from all regions, or only from the region in which it was created.

Type: String

Indicates whether an event data store is collecting logged events for an organization in AWS Organizations.

Type: Boolean RetentionPeriod (p. 33)

The retention period of the event data store, in days.

Type: Integer

Status (p. 33)

The status of an event data store. Values can be ENABLED and PENDING_DELETION.

(42)

Errors

Type: String

Valid Values: CREATED | ENABLED | PENDING_DELETION TerminationProtectionEnabled (p. 33)

Indicates that termination protection is enabled.

Type: Boolean

UpdatedTimestamp (p. 33)

Shows the time that an event data store was updated, if applicable. UpdatedTimestamp is always either the same or newer than the time shown in CreatedTimestamp.

Type: Timestamp

Errors

GetEventSelectors

Describes the settings for the event selectors that you conﬁgured for your trail. The information returned for your event selectors includes the following:

• If your event selector includes read-only events, write-only events, or all events. This applies to both management events and data events.

• If your event selector includes management events.

• If your event selector includes data events, the resources on which you are logging data events.

For more information, see Logging Data and Management Events for Trails in the AWS CloudTrail User Guide.

Request Syntax

{ "TrailName": "string"

}

Request Parameters

TrailName (p. 37)

Speciﬁes the name of the trail or trail ARN. If you specify a trail name, the string must meet the following requirements:

• Not be in IP address format (for example, 192.168.5.4) If you specify a trail ARN, it must be in the format:

Required: Yes

Response Syntax

(45)

Response Elements

],

"Name": "string"

} ],

"EventSelectors": [ {

"DataResources": [ {

"Type": "string", "Values": [ "string" ] }

],

"ExcludeManagementEventSources": [ "string" ], "IncludeManagementEvents": boolean,

"ReadWriteType": "string"

} ],

"TrailARN": "string"

}

Response Elements

The advanced event selectors that are conﬁgured for the trail.

Type: Array of AdvancedEventSelector (p. 110) objects EventSelectors (p. 37)

The event selectors that are conﬁgured for the trail.

Type: Array of EventSelector (p. 121) objects TrailARN (p. 37)

The speciﬁed trail ARN that has the event selectors.

Type: String

Errors

InvalidTrailNameException

(46)

See Also

HTTP Status Code: 400 TrailNotFoundException

This exception is thrown when the trail with the given name is not found.

GetInsightSelectors

Describes the settings for the Insights event selectors that you conﬁgured for your trail.

GetInsightSelectors shows if CloudTrail Insights event logging is enabled on the trail, and if it is, which insight types are enabled. If you run GetInsightSelectors on a trail that does not have Insights events enabled, the operation throws the exception InsightNotEnabledException

For more information, see Logging CloudTrail Insights Events for Trails in the AWS CloudTrail User Guide.

Request Syntax

{

"TrailName": "string"

}

Request Parameters

TrailName (p. 40)

Speciﬁes the name of the trail or trail ARN. If you specify a trail name, the string must meet the following requirements:

• Not be in IP address format (for example, 192.168.5.4) If you specify a trail ARN, it must be in the format:

Required: Yes

Response Syntax

{ "InsightSelectors": [ {

"InsightType": "string"

} ],

"TrailARN": "string"

}

AWS CloudTrail

AWS CloudTrail

API Reference

API Version 2013-11-01

AWS CloudTrail: API Reference

Table of Contents

Welcome

Actions

AddTags

Request Syntax

Request Parameters

Response Elements

Errors

See Also

CancelQuery

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

CreateEventDataStore

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

CreateTrail

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

DeleteEventDataStore

Request Syntax

Request Parameters

Response Elements

Errors

See Also

DeleteTrail

Request Syntax

Request Parameters

Response Elements

Errors

See Also

DescribeQuery

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

DescribeTrails

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

GetEventDataStore

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

GetEventSelectors

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

GetInsightSelectors

Request Syntax

Request Parameters

Response Syntax