}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
CloudWatchLogsLogGroupArn (p. 17)
Specifies the Amazon Resource Name (ARN) of the log group to which CloudTrail logs will be delivered.
Type: String
CloudWatchLogsRoleArn (p. 17)
Specifies the role for the CloudWatch Logs endpoint to assume to write to a user's log group.
Type: String
IncludeGlobalServiceEvents (p. 17)
Specifies whether the trail is publishing events from global services such as IAM to the log files.
Type: Boolean IsMultiRegionTrail (p. 17)
Specifies whether the trail exists in one region or in all regions.
Type: Boolean
IsOrganizationTrail (p. 17)
Specifies whether the trail is an organization trail.
Type: Boolean KmsKeyId (p. 17)
Specifies the AWS KMS key ID that encrypts the logs delivered by CloudTrail. The value is a fully specified 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)
Specifies whether log file integrity validation is enabled.
Type: Boolean Name (p. 17)
Specifies the name of the trail.
Type: String S3BucketName (p. 17)
Specifies the name of the Amazon S3 bucket designated for publishing log files.
Type: String
Errors
S3KeyPrefix (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 field is no longer in use. Use CreateTrail:SnsTopicARN (p. 19).
Type: String TrailARN (p. 17)
Specifies the ARN of the trail that was created. The format of a trail ARN is:
arn:aws:cloudtrail:us-east-2:123456789012:trail/MyTrail Type: String
Errors
For information about the errors that are common to all actions, see Common Errors (p. 138).
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.
HTTP Status Code: 400
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 notifications to an Amazon SNS topic that is in a suspended AWS account.
HTTP Status Code: 400
CloudWatchLogsDeliveryUnavailableException
Cannot set a CloudWatch Logs delivery for this region.
HTTP Status Code: 400 ConflictException
This exception is thrown when the specified 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.
Errors
HTTP Status Code: 400
InsufficientDependencyServiceAccessPermissionException
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.
HTTP Status Code: 400
InsufficientEncryptionPolicyException
This exception is thrown when the policy on the S3 bucket or AWS KMS key is not sufficient.
HTTP Status Code: 400
InsufficientS3BucketPolicyException
This exception is thrown when the policy on the S3 bucket is not sufficient.
HTTP Status Code: 400
InsufficientSnsTopicPolicyException
This exception is thrown when the policy on the Amazon SNS topic is not sufficient.
HTTP Status Code: 400
InvalidCloudWatchLogsLogGroupArnException
This exception is thrown when the provided CloudWatch Logs log group is not valid.
HTTP Status Code: 400
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.
HTTP Status Code: 400
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 InvalidS3PrefixException
This exception is thrown when the provided S3 prefix is not valid.
HTTP Status Code: 400 InvalidSnsTopicNameException
This exception is thrown when the provided SNS topic name is not valid.
Errors
HTTP Status Code: 400 InvalidTagParameterException
This exception is thrown when the specified 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
KmsException
This exception is thrown when there is an issue with the specified 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.
HTTP Status Code: 400
MaximumNumberOfTrailsExceededException
This exception is thrown when the maximum number of trails is reached.
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
See Also
OrganizationNotInAllFeaturesModeException
This exception is thrown when AWS Organizations is not configured 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 specified S3 bucket does not exist.
HTTP Status Code: 400 TrailAlreadyExistsException
This exception is thrown when the specified trail already exists.
HTTP Status Code: 400 TrailNotProvidedException
This exception is no longer in use.
HTTP Status Code: 400 UnsupportedOperationException
This exception is thrown when the requested operation is not supported.
HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
DeleteEventDataStore
DeleteEventDataStore
Disables the event data store specified 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
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.
EventDataStore (p. 23)
The ARN (or the ID suffix of the ARN) of the event data store to delete.
Type: String
Length Constraints: Minimum length of 3. Maximum length of 256.
Pattern: ^[a-zA-Z0-9._/\-:]+$
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).
EventDataStoreARNInvalidException
The specified event data store ARN is not valid or does not map to an event data store in your account.
HTTP Status Code: 400
EventDataStoreNotFoundException
The specified event data store was not found.
See Also
HTTP Status Code: 400
EventDataStoreTerminationProtectedException
The event data store cannot be deleted because termination protection is enabled for it.
HTTP Status Code: 400
InsufficientDependencyServiceAccessPermissionException
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.
HTTP Status Code: 400 InvalidParameterException
The request includes a parameter that is not valid.
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 UnsupportedOperationException
This exception is thrown when the requested operation is not supported.
HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
DeleteTrail
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
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.
Name (p. 25)
Specifies 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
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).
ConflictException
This exception is thrown when the specified 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
InsufficientDependencyServiceAccessPermissionException
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.
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.
See Also
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 TrailNotFoundException
This exception is thrown when the trail with the given name is not found.
HTTP Status Code: 400 UnsupportedOperationException
This exception is thrown when the requested operation is not supported.
HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
DescribeQuery
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
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.
EventDataStore (p. 27)
The ARN (or the ID suffix of the ARN) of an event data store on which the specified query was run.
Type: String
Length Constraints: Minimum length of 3. Maximum length of 256.
Pattern: ^[a-zA-Z0-9._/\-:]+$
Required: Yes QueryId (p. 27)
The query ID.
Type: String
Length Constraints: Fixed length of 36.
Pattern: ^[a-f0-9\-]+$
Required: Yes
Response Syntax
{
"ErrorMessage": "string", "QueryId": "string", "QueryStatistics": { "CreationTime": number, "EventsMatched": number, "EventsScanned": number, "ExecutionTimeInMillis": number },
"QueryStatus": "string", "QueryString": "string"
Response Elements
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
ErrorMessage (p. 27)
The error message returned if a query failed.
Type: String
Length Constraints: Minimum length of 4. Maximum length of 1000.
Pattern: .*
QueryId (p. 27)
The ID of the query.
Type: String
Length Constraints: Fixed length of 36.
Pattern: ^[a-f0-9\-]+$
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
Length Constraints: Minimum length of 1. Maximum length of 10000.
Pattern: (?s).*
Errors
For information about the errors that are common to all actions, see Common Errors (p. 138).
EventDataStoreARNInvalidException
The specified event data store ARN is not valid or does not map to an event data store in your account.
See Also
HTTP Status Code: 400
EventDataStoreNotFoundException
The specified 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 InvalidParameterException
The request includes a parameter that is not valid.
HTTP Status Code: 400 OperationNotPermittedException
This exception is thrown when the requested operation is not permitted.
HTTP Status Code: 400 QueryIdNotFoundException
The query ID does not exist or does not map to a query.
HTTP Status Code: 400 UnsupportedOperationException
This exception is thrown when the requested operation is not supported.
HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
DescribeTrails
DescribeTrails
Retrieves settings for one or more trails associated with the current region for your account.
Request Syntax
{ "includeShadowTrails": boolean, "trailNameList": [ "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.
includeShadowTrails (p. 30)
Specifies 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 different 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)
Specifies 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 specified, information for the trail in the current region is returned.
• If an empty list is specified and IncludeShadowTrails is false, then information for all trails in the current region is returned.
• If an empty list is specified 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 specified, 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": [
Response Elements
{
"CloudWatchLogsLogGroupArn": "string", "CloudWatchLogsRoleArn": "string", "HasCustomEventSelectors": boolean, "HasInsightSelectors": boolean, "HomeRegion": "string",
"IncludeGlobalServiceEvents": boolean, "IsMultiRegionTrail": boolean,
"IsOrganizationTrail": boolean, "KmsKeyId": "string",
"LogFileValidationEnabled": boolean, "Name": "string",
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
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
For information about the errors that are common to all actions, see Common Errors (p. 138).
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
OperationNotPermittedException
This exception is thrown when the requested operation is not permitted.
HTTP Status Code: 400
See Also
UnsupportedOperationException
This exception is thrown when the requested operation is not supported.
HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for C++