# Operations on Buckets (SOAP API)


**Note**  
 SOAP APIs for Amazon S3 are not available for new customers, and are approaching End of Life (EOL) on October 31, 2025. We recommend that you use either the REST API or the Amazon SDKs. 

This section describes operations you can perform on Amazon S3 buckets.

**Topics**
+ [

# CreateBucket (SOAP API)
](SOAPCreateBucket.md)
+ [

# DeleteBucket (SOAP API)
](SOAPDeleteBucket.md)
+ [

# ListBucket (SOAP API)
](SOAPListBucket.md)
+ [

# GetBucketAccessControlPolicy (SOAP API)
](SOAPGetBucketAccessControlPolicy.md)
+ [

# SetBucketAccessControlPolicy (SOAP API)
](SOAPSetBucketAccessControlPolicy.md)
+ [

# GetBucketLoggingStatus (SOAP API)
](SOAPGetBucketLoggingStatus.md)
+ [

# SetBucketLoggingStatus (SOAP API)
](SOAPSetBucketLoggingStatus.md)

# CreateBucket (SOAP API)


**Note**  
 SOAP APIs for Amazon S3 are not available for new customers, and are approaching End of Life (EOL) on October 31, 2025. We recommend that you use either the REST API or the Amazon SDKs. 

The `CreateBucket` operation creates a bucket. Not every string is an acceptable bucket name. For information on bucket naming restrictions, see [Working with Amazon S3 Buckets](https://docs.amazonaws.cn/AmazonS3/latest/userguide/UsingBucket.html) .

**Note**  
 To determine whether a bucket name exists, use `ListBucket` and set `MaxKeys` to 0. A NoSuchBucket response indicates that the bucket is available, an AccessDenied response indicates that someone else owns the bucket, and a Success response indicates that you own the bucket or have permission to access it. 

**Example Create a bucket named "quotes"**  
`Sample Request`  

```
1. <CreateBucket xmlns="http://doc.s3.amazonaws.com/2006-03-01">
2.   <Bucket>quotes</Bucket>
3.   <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
4.   <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
5.   <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
6. </CreateBucket>
```
`Sample Response`  

```
1. <CreateBucketResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
2.   <CreateBucketResponse>
3.     <Bucket>quotes</Bucket>
4.   </CreateBucketResponse>
5. </CreateBucketResponse>
```

## Elements

+ `Bucket:` The name of the bucket you are trying to create. 

  
+ `AccessControlList:` The access control list for the new bucket. This element is optional. If not provided, the bucket is created with an access policy that give the requester FULL\$1CONTROL access.

  

## Access Control


You must authenticate with a valid Amazon Access Key ID. Anonymous requests are never allowed to create buckets.

## Related Resources

+  [ListBucket (SOAP API)](SOAPListBucket.md) 

# DeleteBucket (SOAP API)


**Note**  
 SOAP APIs for Amazon S3 are not available for new customers, and are approaching End of Life (EOL) on October 31, 2025. We recommend that you use either the REST API or the Amazon SDKs. 

The `DeleteBucket` operation deletes a bucket. All objects in the bucket must be deleted before the bucket itself can be deleted.

**Example**  
This example deletes the "quotes" bucket.  
`Sample Request`  

```
1. <DeleteBucket xmlns="http://doc.s3.amazonaws.com/2006-03-01">
2.   <Bucket>quotes</Bucket>
3.   <AWSAccessKeyId> AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
4.   <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
5.   <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
6. </DeleteBucket>
```
`Sample Response`  

```
1. <DeleteBucketResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
2.   <DeleteBucketResponse>
3.     <Code>204</Code>
4.     <Description>No Content</Description>
5.   </DeleteBucketResponse>
6. </DeleteBucketResponse>
```

## Elements

+ `Bucket:` The name of the bucket you want to delete.

## Access Control


Only the owner of a bucket is allowed to delete it, regardless the access control policy on the bucket.

# ListBucket (SOAP API)


**Note**  
 SOAP APIs for Amazon S3 are not available for new customers, and are approaching End of Life (EOL) on October 31, 2025. We recommend that you use either the REST API or the Amazon SDKs. 

 The `ListBucket` operation returns information about some of the items in the bucket. 

 For a general introduction to the list operation, see the [Listing Object Keys](https://docs.amazonaws.cn/AmazonS3/latest/userguide/ListingKeysUsingAPIs.html).

## Requests


This example lists up to 1000 keys in the "quotes" bucket that have the prefix "notes."

### Syntax


```
1. <ListBucket xmlns="http://doc.s3.amazonaws.com/2006-03-01">
2.   <Bucket>quotes</Bucket>
3.   <Prefix>notes/</Prefix>
4.   <Delimiter>/</Delimiter>
5.   <MaxKeys>1000</MaxKeys>
6.   <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
7.   <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
8.   <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
9. </ListBucket>
```

### Parameters



|  Name  |  Description  |  Required  | 
| --- | --- | --- | 
|  prefix  |  Limits the response to keys which begin with the indicated prefix. You can use prefixes to separate a bucket into different sets of keys in a way similar to how a file system uses folders. Replacement must be made for object keys containing special characters (such as carriage returns) when using XML requests. For more information, see [ XML related object key constraints](https://docs.amazonaws.cn/AmazonS3/latest/userguide/object-keys.html#object-key-xml-related-constraints). Type: String Default: None  |  No  | 
|  marker  |  Indicates where in the bucket to begin listing. The list will only include keys that occur lexicographically after marker. This is convenient for pagination: To get the next page of results use the last key of the current page as the marker. Type: String Default: None  |  No  | 
|  max-keys  |  The maximum number of keys you'd like to see in the response body. The server might return fewer than this many keys, but will not return more. Type: String Default: None  |  No  | 
|  delimiter  |  Causes keys that contain the same string between the prefix and the first occurrence of the delimiter to be rolled up into a single result element in the CommonPrefixes collection. These rolled-up keys are not returned elsewhere in the response. Type: String Default: None  |  No  | 

## Success Response


This response assumes the bucket contains the following keys:

```
1. notes/todos.txt
2. notes/2005-05-23/customer_mtg_notes.txt
3. notes/2005-05-23/phone_notes.txt
4. notes/2005-05-28/sales_notes.txt
```

### Syntax


```
 1. <?xml version="1.0" encoding="UTF-8"?>
 2. <ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
 3.   <Name>backups</Name>
 4.   <Prefix>notes/</Prefix>
 5.   <MaxKeys>1000</MaxKeys>
 6.   <Delimiter>/</Delimiter>
 7.   <IsTruncated>false</IsTruncated>
 8.   <Contents>
 9.     <Key>notes/todos.txt</Key>
10.     <LastModified>2006-01-01T12:00:00.000Z</LastModified>
11.     <ETag>&quot;828ef3fdfa96f00ad9f27c383fc9ac7f&quot;</ETag>
12.     <Size>5126</Size>
13.     <StorageClass>STANDARD</StorageClass>
14.     <Owner>
15.       <ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
16.       <DisplayName>webfile</DisplayName>
17.     </Owner>
18.     <StorageClass>STANDARD</StorageClass>
19.   </Contents>
20.   <CommonPrefixes>
21.     <Prefix>notes/2005-05-23/</Prefix>
22.   </CommonPrefixes>
23.   <CommonPrefixes>
24.     <Prefix>notes/2005-05-28/</Prefix>
25.   </CommonPrefixes>
26.   </ListBucketResult>
```

As you can see, many of the fields in the response echo the request parameters. `IsTruncated`, `Contents`, and `CommonPrefixes` are the only response elements that can contain new information.

### Response Elements



|  Name  |  Description  | 
| --- | --- | 
|  Contents  |  Metadata about each object returned. Type: XML metadata Ancestor: ListBucketResult  | 
|  CommonPrefixes  |   A response can contain `CommonPrefixes` only if you specify a `delimiter`. When you do, `CommonPrefixes` contains all (if there are any) keys between `Prefix` and the next occurrence of the string specified by `delimiter`. In effect, `CommonPrefixes` lists keys that act like subdirectories in the directory specified by `Prefix`. For example, if `prefix` is `notes/` and `delimiter` is a slash (/), in `notes/summer/july`, the common prefix is `notes/summer/`.  Type: String Ancestor: ListBucketResult  | 
|  Delimiter  |  Causes keys that contain the same string between the prefix and the first occurrence of the delimiter to be rolled up into a single result element in the CommonPrefixes collection. These rolled-up keys are not returned elsewhere in the response. Type: String Ancestor: ListBucketResult  | 
|  IsTruncated  |  Specifies whether (true) or not (false) all of the results were returned. All of the results may not be returned if the number of results exceeds that specified by `MaxKeys`. Type: String Ancestor: boolean  | 
|  Marker  |  Indicates where in the bucket to begin listing. Type: String Ancestor: ListBucketResult  | 
|  MaxKeys  |  The maximum number of keys returned in the response body. Type: String Ancestor: ListBucketResult  | 
|  Name  |  Name of the bucket. Type: String Ancestor: ListBucketResult  | 
|  Prefix  |  Keys that begin with the indicated prefix. Type: String Ancestor: ListBucketResult  | 

## Response Body


 For information about the list response, see [Listing Keys Response](https://docs.amazonaws.cn/AmazonS3/latest/userguide/ListingKeysUsingAPIs.html). 

## Access Control


To list the keys of a bucket you need to have been granted `READ` access on the bucket.

# GetBucketAccessControlPolicy (SOAP API)


**Note**  
 SOAP APIs for Amazon S3 are not available for new customers, and are approaching End of Life (EOL) on October 31, 2025. We recommend that you use either the REST API or the Amazon SDKs. 

The `GetBucketAccessControlPolicy` operation fetches the access control policy for a bucket.

**Example**  
This example retrieves the access control policy for the "quotes" bucket.  
`Sample Request`  

```
1. <GetBucketAccessControlPolicy xmlns="http://doc.s3.amazonaws.com/2006-03-01">
2.   <Bucket>quotes</Bucket>
3.   <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
4.   <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
5.   <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
6. </GetBucketAccessControlPolicy>
```
`Sample Response`  

```
 1. <AccessControlPolicy>
 2.   <Owner>
 3.     <ID>a9a7b886d6fd2441bf9b1c61be666e9</ID>
 4.     <DisplayName>chriscustomer</DisplayName>
 5.   </Owner>
 6.   <AccessControlList>
 7.     <Grant>
 8.       <Grantee xsi:type="CanonicalUser">
 9.         <ID>a9a7b886d6f41bf9b1c61be666e9</ID>
10.         <DisplayName>chriscustomer</DisplayName>
11.       </Grantee>
12.       <Permission>FULL_CONTROL</Permission>
13.     </Grant>
14.     <Grant>
15.       <Grantee xsi:type="Group">
16.         <URI>http://acs.amazonaws.com/groups/global/AllUsers<URI>
17.       </Grantee>
18.       <Permission>READ</Permission>
19.     </Grant>
20.   </AccessControlList>
21. <AccessControlPolicy>
```

## Response Body


The response contains the access control policy for the bucket. For an explanation of this response, see [SOAP Access Policy](https://docs.amazonaws.cn/AmazonS3/latest/userguide/SOAPAccessPolicy.html) . 

## Access Control


You must have `READ_ACP` rights to the bucket in order to retrieve the access control policy for a bucket.

# SetBucketAccessControlPolicy (SOAP API)


**Note**  
 SOAP APIs for Amazon S3 are not available for new customers, and are approaching End of Life (EOL) on October 31, 2025. We recommend that you use either the REST API or the Amazon SDKs. 

The `SetBucketAccessControlPolicy` operation sets the Access Control Policy for an existing bucket. If successful, the previous Access Control Policy for the bucket is entirely replaced with the specified Access Control Policy.

**Example**  
Give the specified user (usually the owner) `FULL_CONTROL` access to the "quotes" bucket.  
`Sample Request`  

```
 1. <SetBucketAccessControlPolicy xmlns="http://doc.s3.amazonaws.com/2006-03-01">
 2.   <Bucket>quotes</Bucket>
 3.   <AccessControlList>
 4.     <Grant>
 5.       <Grantee xsi:type="CanonicalUser">
 6.         <ID>a9a7b8863000e241bf9b1c61be666e9</ID>
 7.         <DisplayName>chriscustomer</DisplayName>
 8.       </Grantee>
 9.       <Permission>FULL_CONTROL</Permission>
10.     </Grant>
11.   </AccessControlList>
12.   <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
13.   <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
14.   <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
15. </SetBucketAccessControlPolicy >
```
`Sample Response`  

```
1. <GetBucketAccessControlPolicyResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
2.   <GetBucketAccessControlPolicyResponse>
3.     <Code>200</Code>
4.     <Description>OK</Description>
5.   </GetBucketAccessControlPolicyResponse>
6. </GetBucketAccessControlPolicyResponse>
```

## Access Control


You must have `WRITE_ACP` rights to the bucket in order to set the access control policy for a bucket.

# GetBucketLoggingStatus (SOAP API)


**Note**  
 SOAP APIs for Amazon S3 are not available for new customers, and are approaching End of Life (EOL) on October 31, 2025. We recommend that you use either the REST API or the Amazon SDKs. 

 The `GetBucketLoggingStatus` retrieves the logging status for an existing bucket. 

 For a general introduction to this feature, see [Server Logs](https://docs.amazonaws.cn/AmazonS3/latest/userguide/ServerLogs.html). 

**Example**  
`Sample Request`  

```
 1. <?xml version="1.0" encoding="utf-8"?>
 2.     <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 3.       <soap:Body>
 4.         <GetBucketLoggingStatus xmlns="http://doc.s3.amazonaws.com/2006-03-01">
 5.           <Bucket>mybucket</Bucket>
 6.           <AWSAccessKeyId>YOUR_AWS_ACCESS_KEY_ID</AWSAccessKeyId>
 7.           <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
 8.           <Signature>YOUR_SIGNATURE_HERE</Signature>
 9.         </GetBucketLoggingStatus>
10.       </soap:Body>
11.     </soap:Envelope>
```
`Sample Response`  

```
 1. <?xml version="1.0" encoding="utf-8"?>
 2.     <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
 3.       <soapenv:Header>
 4.       </soapenv:Header>
 5.       <soapenv:Body>
 6.         <GetBucketLoggingStatusResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
 7.           <GetBucketLoggingStatusResponse>
 8.             <LoggingEnabled>
 9.               <TargetBucket>mylogs</TargetBucket>
10.               <TargetPrefix>mybucket-access_log-</TargetPrefix>
11.             </LoggingEnabled>
12.           </GetBucketLoggingStatusResponse>
13.         </GetBucketLoggingStatusResponse>
14.       </soapenv:Body>
15.     </soapenv:Envelope>
```

## Access Control


Only the owner of a bucket is permitted to invoke this operation.

# SetBucketLoggingStatus (SOAP API)


**Note**  
 SOAP APIs for Amazon S3 are not available for new customers, and are approaching End of Life (EOL) on October 31, 2025. We recommend that you use either the REST API or the Amazon SDKs. 

 The `SetBucketLoggingStatus` operation updates the logging status for an existing bucket. 

 For a general introduction to this feature, see [Server Logs](https://docs.amazonaws.cn/AmazonS3/latest/userguide/ServerLogs.html). 

**Example**  
This sample request enables server access logging for the 'mybucket' bucket, and configures the logs to be delivered to 'mylogs' under prefix 'access\$1log-'  
`Sample Request`  

```
 1. <?xml version="1.0" encoding="utf-8"?>
 2.     <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 3.     <soap:Body>
 4.     <SetBucketLoggingStatus xmlns="http://doc.s3.amazonaws.com/2006-03-01">
 5.       <Bucket>myBucket</Bucket>
 6.       <AWSAccessKeyId>YOUR_AWS_ACCESS_KEY_ID</AWSAccessKeyId>
 7.       <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
 8.       <Signature>YOUR_SIGNATURE_HERE</Signature>
 9.       <BucketLoggingStatus>
10.         <LoggingEnabled>
11.           <TargetBucket>mylogs</TargetBucket>
12.           <TargetPrefix>mybucket-access_log-</TargetPrefix>
13.         </LoggingEnabled>
14.       </BucketLoggingStatus>
15.     </SetBucketLoggingStatus>
16.     </soap:Body>
17.     :</soap:Envelope>
```
`Sample Response`  

```
1. <?xml version="1.0" encoding="utf-8"?>
2.     <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
3.       <soapenv:Header>
4.       </soapenv:Header>
5.       <soapenv:Body>
6.         <SetBucketLoggingStatusResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01"/>
7.       </soapenv:Body>
8.     </soapenv:Envelope>
```

## Access Control


Only the owner of a bucket is permitted to invoke this operation.