StartImport - AWS CloudTrail

StartImport

Starts an import of logged trail events from a source S3 bucket to a destination event data store. By default, CloudTrail only imports events contained in the S3 bucket's CloudTrail prefix and the prefixes inside the CloudTrail prefix, and does not check prefixes for other AWS services. If you want to import CloudTrail events contained in another prefix, you must include the prefix in the S3LocationUri. For more considerations about importing trail events, see Considerations for copying trail events in the CloudTrail User Guide.

When you start a new import, the Destinations and ImportSource parameters are required. Before starting a new import, disable any access control lists (ACLs) attached to the source S3 bucket. For more information about disabling ACLs, see Controlling ownership of objects and disabling ACLs for your bucket.

When you retry an import, the ImportID parameter is required.

Note

If the destination event data store is for an organization, you must use the management account to import trail events. You cannot use the delegated administrator account for the organization.

Request Syntax

{ "Destinations": [ "string" ], "EndEventTime": number, "ImportId": "string", "ImportSource": { "S3": { "S3BucketAccessRoleArn": "string", "S3BucketRegion": "string", "S3LocationUri": "string" } }, "StartEventTime": number }

Request Parameters

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

The request accepts the following data in JSON format.

Destinations

The ARN of the destination event data store. Use this parameter for a new import.

Type: Array of strings

Array Members: Fixed number of 1 item.

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

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

Required: No

EndEventTime

Use with StartEventTime to bound a StartImport request, and limit imported trail events to only those events logged within a specified time period. When you specify a time range, CloudTrail checks the prefix and log file names to verify the names contain a date between the specified StartEventTime and EndEventTime before attempting to import events.

Type: Timestamp

Required: No

ImportId

The ID of the import. Use this parameter when you are retrying an import.

Type: String

Length Constraints: Fixed length of 36.

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

Required: No

ImportSource

The source S3 bucket for the import. Use this parameter for a new import.

Type: ImportSource object

Required: No

StartEventTime

Use with EndEventTime to bound a StartImport request, and limit imported trail events to only those events logged within a specified time period. When you specify a time range, CloudTrail checks the prefix and log file names to verify the names contain a date between the specified StartEventTime and EndEventTime before attempting to import events.

Type: Timestamp

Required: No

Response Syntax

{ "CreatedTimestamp": number, "Destinations": [ "string" ], "EndEventTime": number, "ImportId": "string", "ImportSource": { "S3": { "S3BucketAccessRoleArn": "string", "S3BucketRegion": "string", "S3LocationUri": "string" } }, "ImportStatus": "string", "StartEventTime": number, "UpdatedTimestamp": number }

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.

CreatedTimestamp

The timestamp for the import's creation.

Type: Timestamp

Destinations

The ARN of the destination event data store.

Type: Array of strings

Array Members: Fixed number of 1 item.

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

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

EndEventTime

Used with StartEventTime to bound a StartImport request, and limit imported trail events to only those events logged within a specified time period.

Type: Timestamp

ImportId

The ID of the import.

Type: String

Length Constraints: Fixed length of 36.

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

ImportSource

The source S3 bucket for the import.

Type: ImportSource object

ImportStatus

Shows the status of the import after a StartImport request. An import finishes with a status of COMPLETED if there were no failures, or FAILED if there were failures.

Type: String

Valid Values: INITIALIZING | IN_PROGRESS | FAILED | STOPPED | COMPLETED

StartEventTime

Used with EndEventTime to bound a StartImport request, and limit imported trail events to only those events logged within a specified time period.

Type: Timestamp

UpdatedTimestamp

The timestamp of the import's last update, if applicable.

Type: Timestamp

Errors

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

AccountHasOngoingImportException

This exception is thrown when you start a new import and a previous import is still in progress.

HTTP Status Code: 400

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.

HTTP Status Code: 400

ImportNotFoundException

The specified import was not found.

HTTP Status Code: 400

InactiveEventDataStoreException

The event data store is inactive.

HTTP Status Code: 400

InsufficientEncryptionPolicyException

This exception is thrown when the policy on the S3 bucket or AWS KMS key does not have sufficient permissions for the operation.

HTTP Status Code: 400

InvalidEventDataStoreCategoryException

This exception is thrown when event categories of specified event data stores are not valid.

HTTP Status Code: 400

InvalidEventDataStoreStatusException

The event data store is not in a status that supports the operation.

HTTP Status Code: 400

InvalidImportSourceException

This exception is thrown when the provided source S3 bucket is not valid for import.

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

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

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: