# Operations on Objects (SOAP API)
<a name="SOAPObjectsOps"></a>

**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 AWS SDKs. 

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

**Topics**
+ [

# PutObjectInline (SOAP API)
](SOAPPutObjectInline.md)
+ [

# PutObject (SOAP API)
](SOAPPutObject.md)
+ [

# CopyObject (SOAP API)
](SOAPCopyObject.md)
+ [

# GetObject (SOAP API)
](SOAPGetObject.md)
+ [

# GetObjectExtended (SOAP API)
](SOAPGetObjectExtended.md)
+ [

# DeleteObject (SOAP API)
](SOAPDeleteObject.md)
+ [

# GetObjectAccessControlPolicy (SOAP API)
](SOAPGetObjectAccessControlPolicy.md)
+ [

# SetObjectAccessControlPolicy (SOAP API)
](SOAPSetObjectAccessControlPolicy.md)

# PutObjectInline (SOAP API)
<a name="SOAPPutObjectInline"></a>

**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 AWS SDKs. 

The `PutObjectInline` operation adds an object to a bucket. The data for the object is provided in the body of the SOAP message. 

If an object already exists in a bucket, the new object will overwrite it because Amazon S3 stores the last write request. However, Amazon S3 is a distributed system. If Amazon S3 receives multiple write requests for the same object nearly simultaneously, all of the objects might be stored, even though only one wins in the end. Amazon S3 does not provide object locking; if you need this, make sure to build it into your application layer.

To ensure an object is not corrupted over the network, you can calculate the MD5 of an object, PUT it to Amazon S3, and compare the returned Etag to the calculated MD5 value.

PutObjectInline is not suitable for use with large objects. The system limits this operation to working with objects 1MB or smaller. PutObjectInline will fail with the `InlineDataTooLargeError` status code if the Data parameter encodes an object larger than 1MB. To upload large objects, consider using the non-inline PutObject API, or the REST API instead. 

**Example**  
This example writes some text and metadata into the "Nelson" object in the "quotes" bucket, give a user (usually the owner) `FULL_CONTROL` access to the object, and make the object readable by anonymous parties.  
`Sample Request`  

```
 1. <PutObjectInline xmlns="http://doc.s3.amazonaws.com/2006-03-01">
 2.   <Bucket>quotes</Bucket>
 3.   <Key>Nelson</Key>
 4.   <Metadata>
 5.     <Name>Content-Type</Name>
 6.     <Value>text/plain</Value>
 7.   </Metadata>
 8.   <Metadata>
 9.     <Name>family</Name>
10.     <Value>Muntz</Value>
11.   </Metadata>
12.   <Data>aGEtaGE=</Data>
13.   <ContentLength>5</ContentLength>
14.   <AccessControlList>
15.     <Grant>
16.       <Grantee xsi:type="CanonicalUser">
17.         <ID>a9a7b886d6fde241bf9b1c61be666e9</ID>
18.         <DisplayName>chriscustomer</DisplayName>
19.       </Grantee>
20.       <Permission>FULL_CONTROL</Permission>
21.     </Grant>
22.     <Grant>
23.       <Grantee xsi:type="Group">
24.         <URI>http://acs.amazonaws.com/groups/global/AllUsers</URI>
25.       </Grantee>
26.       <Permission>READ</Permission>
27.     </Grant>
28.   </AccessControlList>
29.   <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
30.   <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
31.   <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
32. </PutObjectInline>
```
`Sample Response`  

```
1. <PutObjectInlineResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
2.   <PutObjectInlineResponse>
3.     <ETag>&quot828ef3fdfa96f00ad9f27c383fc9ac7f&quot</ETag>
4.     <LastModified>2006-01-01T12:00:00.000Z</lastModified>
5.   </PutObjectInlineResponse>
6. </PutObjectInlineResponse>
```

## Elements
<a name="SOAPPutObjectInlineElements"></a>
+ `Bucket:` The bucket in which to add the object.

  
+ `Key:` The key to assign to the object.
**Important**  
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.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html#object-key-xml-related-constraints).

  
+ `Metadata:` You can provide name-value metadata pairs in the metadata element. These will be stored with the object.

  
+ `Data:` The base 64 encoded form of the data.

  
+ `ContentLength:` The length of the data in bytes.

  
+ `AccessControlList:` An Access Control List for the resource. This element is optional. If omitted, the requester is given `FULL_CONTROL` access to the object. If the object already exists, the preexisting access control policy is replaced.

  

## Responses
<a name="SOAPPutObjectInlineResponse"></a>
+  `ETag:` The entity tag is an MD5 hash of the object that you can use to do conditional fetches of the object using `GetObjectExtended`. The ETag only reflects changes to the contents of an object, not its metadata. 
+ `LastModified:` The Amazon S3 timestamp for the saved object.

## Access Control
<a name="SOAPPutObjectInlineAccessControl"></a>

You must have `WRITE` access to the bucket in order to put objects into the bucket. 

## Related Resources
<a name="SOAPPutObjectInline_RelatedResources"></a>
+  [PutObject (SOAP API)](SOAPPutObject.md) 
+  [CopyObject (SOAP API)](SOAPCopyObject.md) 

# PutObject (SOAP API)
<a name="SOAPPutObject"></a>

**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 AWS SDKs. 

The `PutObject` operation adds an object to a bucket. The data for the object is attached as a DIME attachment.

To ensure an object is not corrupted over the network, you can calculate the MD5 of an object, PUT it to Amazon S3, and compare the returned Etag to the calculated MD5 value.

If an object already exists in a bucket, the new object will overwrite it because Amazon S3 stores the last write request. However, Amazon S3 is a distributed system. If Amazon S3 receives multiple write requests for the same object nearly simultaneously, all of the objects might be stored, even though only one wins in the end. Amazon S3 does not provide object locking; if you need this, make sure to build it into your application layer.

**Example**  
This example puts some data and metadata in the "Nelson" object of the "quotes" bucket, give a user (usually the owner) `FULL_CONTROL` access to the object, and make the object readable by anonymous parties. In this sample, the actual attachment is not shown.  
`Sample Request`  

```
 1. <PutObject xmlns="http://doc.s3.amazonaws.com/2006-03-01">
 2.   <Bucket>quotes</Bucket>
 3.   <Key>Nelson</Key>
 4.   <Metadata>
 5.     <Name>Content-Type</Name>
 6.     <Value>text/plain</Value>
 7.   </Metadata>
 8.   <Metadata>
 9.     <Name>family</Name>
10.     <Value>Muntz</Value>
11.   </Metadata>
12.   <ContentLength>5</ContentLength>
13.   <AccessControlList>
14.     <Grant>
15.       <Grantee xsi:type="CanonicalUser">
16.         <ID>a9a7b886d6241bf9b1c61be666e9</ID>
17.         <DisplayName>chriscustomer</DisplayName>
18.       </Grantee>
19.       <Permission>FULL_CONTROL</Permission>
20.     </Grant>
21.     <Grant>
22.       <Grantee xsi:type="Group">
23.         <URI>http://acs.amazonaws.com/groups/global/AllUsers<URI>
24.       </Grantee>
25.       <Permission>READ</Permission>
26.     </Grant>
27.   </AccessControlList>
28.   <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
29.   <Timestamp>2007-05-11T12:00:00.183Z</Timestamp>
30.   <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
31. </PutObject>
```
`Sample Response`  

```
1. <PutObjectResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
2.   <PutObjectResponse>
3.     <ETag>&quot;828ef3fdfa96f00ad9f27c383fc9ac7f&quot;</ETag>
4.     <LastModified>2006-03-01T12:00:00.183Z</LastModified>
5.   </PutObjectResponse>
6. </PutObjectResponse>
```

## Elements
<a name="SOAPPutObjectElements"></a>
+  `Bucket:` The bucket in which to add the object.
+ `Key:` The key to assign to the object.
**Important**  
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.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html#object-key-xml-related-constraints).
+ `Metadata:` You can provide name-value metadata pairs in the metadata element. These will be stored with the object.
+ `ContentLength:` The length of the data in bytes.
+ `AccessControlList:` An Access Control List for the resource. This element is optional. If omitted, the requester is given `FULL_CONTROL` access to the object. If the object already exists, the preexisting Access Control Policy is replaced.

## Responses
<a name="SOAPPutObjectResponse"></a>
+ `ETag:` The entity tag is an MD5 hash of the object that you can use to do conditional fetches of the object using `GetObjectExtended`. The ETag only reflects changes to the contents of an object, not its metadata.
+ `LastModified:` The Amazon S3 timestamp for the saved object.

## Access Control
<a name="SOAPPutObjectAccessControl"></a>

To put objects into a bucket, you must have `WRITE` access to the bucket.

## Related Resources
<a name="SOAPPutObject_RelatedResources"></a>
+  [CopyObject (SOAP API)](SOAPCopyObject.md) 

# CopyObject (SOAP API)
<a name="SOAPCopyObject"></a>

**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 AWS SDKs. 

## Description
<a name="SOAPCopyObject_Description"></a>

The `CopyObject` operation creates a copy of an object when you specify the key and bucket of a source object and the key and bucket of a target destination. 

When copying an object, you can preserve all metadata (default) or specify new metadata. However, the ACL is not preserved and is set to `private` for the user making the request. To override the default ACL setting, specify a new ACL when generating a copy request. For more information, see [Using ACLs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/S3_ACLs_UsingACLs.html).

All copy requests must be authenticated. Additionally, you must have *read* access to the source object and *write* access to the destination bucket. For more information, see [Using Auth Access](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-access-control.html). 

To only copy an object under certain conditions, such as whether the Etag matches or whether the object was modified before or after a specified date, use the request parameters `CopySourceIfUnmodifiedSince`, `CopyIfUnmodifiedSince`, `CopySourceIfMatch`, or `CopySourceIfNoneMatch`. 

**Note**  
 You might need to configure the SOAP stack socket timeout for copying large objects. 

## Request Syntax
<a name="SOAPCopyObject_RequestSyntax"></a>

```
 1. <CopyObject xmlns="http://bucket_name.s3.amazonaws.com/2006-03-01">
 2.   <SourceBucket>source_bucket</SourceBucket>
 3.   <SourceObject>source_object</SourceObject>
 4.   <DestinationBucket>destination_bucket</DestinationBucket>
 5.   <DestinationObject>destination_object</DestinationObject>
 6.   <MetadataDirective>{REPLACE | COPY}</MetadataDirective>
 7.   <Metadata>
 8.     <Name>metadata_name</Name>
 9.     <Value>metadata_value</Value>
10.   </Metadata>
11.   ...
12.   <AccessControlList>
13.     <Grant>
14.       <Grantee xsi:type="user_type">
15.         <ID>user_id</ID>
16.         <DisplayName>display_name</DisplayName>
17.       </Grantee>
18.       <Permission>permission</Permission>
19.     </Grant>
20.     ...
21.   </AccessControlList>
22.   <CopySourceIfMatch>etag</CopySourceIfMatch>
23.   <CopySourceIfNoneMatch>etag</CopySourceIfNoneMatch>
24.   <CopySourceIfModifiedSince>date_time</CopySourceIfModifiedSince>
25.   <CopySourceIfUnmodifiedSince>date_time</CopySourceIfUnmodifiedSince>
26.   <AWSAccessKeyId>AWSAccessKeyId</AWSAccessKeyId>
27.   <Timestamp>TimeStamp</Timestamp>
28.   <Signature>Signature</Signature>
29. </CopyObject>
```

## Request Parameters
<a name="SOAPCopyObject_RequestParameters"></a>


|  Name  |  Description  |  Required  | 
| --- | --- | --- | 
|  SourceBucket  |  The name of the source bucket. Type: String Default: None Constraints: A valid source bucket.  |  Yes  | 
|  SourceKey  |  The key name of the source object. Type: String Default: None Constraints: The key for a valid source object to which you have READ access. 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.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html#object-key-xml-related-constraints).  |  Yes  | 
|  DestinationBucket  |  The name of the destination bucket. Type: String Default: None Constraints: You must have WRITE access to the destination bucket.  |  Yes  | 
|  DestinationKey  |   The key of the destination object. Type: String Default: None Constraints: You must have WRITE access to the destination bucket.  |  Yes  | 
|  MetadataDirective  |   Specifies whether the metadata is copied from the source object or replaced with metadata provided in the request. Type: String Default: COPY Valid values: COPY \$1 REPLACE Constraints: Values other than `COPY` or `REPLACE` will result in an immediate error. You cannot copy an object to itself unless the MetadataDirective header is specified and its value set to `REPLACE`.  |  No  | 
|  Metadata  |   Specifies metadata name-value pairs to set for the object.If MetadataDirective is set to `COPY`, all metadata is ignored. Type: String Default: None Constraints: None.  |  No  | 
|  AccessControlList  |  Grants access to users by e-mail addresses or canonical user ID. Type: String Default: None Constraints: None  |  No  | 
|  CopySourceIfMatch  |  Copies the object if its entity tag (ETag) matches the specified tag; otherwise return a PreconditionFailed. Type: String Default: None Constraints: None. If the Etag does not match, the object is not copied.  |  No  | 
|  CopySourceIfNoneMatch  |  Copies the object if its entity tag (ETag) is different than the specified Etag; otherwise returns an error. Type: String Default: None Constraints: None.   |  No  | 
|  CopySourceIfUnmodifiedSince  |   Copies the object if it hasn't been modified since the specified time; otherwise returns a PreconditionFailed. Type: dateTime Default: None  |  No  | 
|  CopySourceIfModifiedSince  |  Copies the object if it has been modified since the specified time; otherwise returns an error. Type: dateTime Default: None  |  No  | 

## Response Syntax
<a name="SOAPCopyObject_ResponseSyntax"></a>

```
1. <CopyObjectResponse xmlns="http://bucket_name.s3.amazonaws.com/2006-03-01">
2.   <CopyObjectResponse>
3.     <ETag>"etag"</ETag>
4.     <LastModified>timestamp</LastModified>
5.   </CopyObjectResponse>
6. </CopyObjectResponse>
```

## Response Elements
<a name="SOAPCopyObject_CommonResponseElements"></a>

Following is a list of response elements.

**Note**  
 The SOAP API does not return extra whitespace. Extra whitespace is only returned by the REST API. 


|  Name  |  Description  | 
| --- | --- | 
|  Etag  |  Returns the etag of the new object. The ETag only reflects changes to the contents of an object, not its metadata. Type: String Ancestor: CopyObjectResult  | 
|  LastModified  |  Returns the date the object was last modified. Type: String Ancestor: CopyObjectResult  | 

For information about general response elements, see [Using REST Error Response Headers](https://docs.aws.amazon.com/AmazonS3/latest/userguide/HandlingErrors.html#UsingRESTErrorResponseHeaders).

## Special Errors
<a name="SOAPCopyObject_SpecialErrors"></a>

There are no special errors for this operation. For information about general Amazon S3 errors, see [List of error codes](ErrorResponses.md#ErrorCodeList).

## Examples
<a name="SOAPCopyObject_Examples"></a>

This example copies the `flotsam` object from the `pacific` bucket to the `jetsam` object of the `atlantic` bucket, preserving its metadata.

### Sample Request
<a name="SOAPCopyObject_Examples_Request1"></a>

```
1. <CopyObject xmlns="http://doc.s3.amazonaws.com/2006-03-01">
2.   <SourceBucket>pacific</SourceBucket>
3.   <SourceObject>flotsam</SourceObject>
4.   <DestinationBucket>atlantic</DestinationBucket>
5.   <DestinationObject>jetsam</DestinationObject>
6.   <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
7.   <Timestamp>2008-02-18T13:54:10.183Z</Timestamp>
8.   <Signature>Iuyz3d3P0aTou39dzbq7RrtSFmw=</Signature>
9. </CopyObject>
```

### Sample Response
<a name="SOAPCopyObject_Examples_Response1"></a>

```
1. <CopyObjectResponse xmlns="http://doc.s3.amazonaws.com/2006-03-01">
2.   <CopyObjectResponse>
3.     <ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
4.     <LastModified>2008-02-18T13:54:10.183Z</LastModified>
5.   </CopyObjectResponse>
6. </CopyObjectResponse>
```

This example copies the "tweedledee" object from the wonderland bucket to the "tweedledum" object of the wonderland bucket, replacing its metadata.

### Sample Request
<a name="SOAPCopyObject_Examples_Request2"></a>

```
 1. <CopyObject xmlns="http://doc.s3.amazonaws.com/2006-03-01">
 2.   <SourceBucket>wonderland</SourceBucket>
 3.   <SourceObject>tweedledee</SourceObject>
 4.   <DestinationBucket>wonderland</DestinationBucket>
 5.   <DestinationObject>tweedledum</DestinationObject>
 6.   <MetadataDirective >REPLACE</MetadataDirective >
 7.   <Metadata>
 8.     <Name>Content-Type</Name>
 9.     <Value>text/plain</Value>
10.   </Metadata>
11.   <Metadata>
12.     <Name>relationship</Name>
13.     <Value>twins</Value>
14.   </Metadata>
15.   <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
16.   <Timestamp>2008-02-18T13:54:10.183Z</Timestamp>
17.   <Signature>Iuyz3d3P0aTou39dzbq7RrtSFmw=</Signature>
18. </CopyObject>
```

### Sample Response
<a name="SOAPCopyObject_Examples_Response2"></a>

```
1. <CopyObjectResponse xmlns="http://doc.s3.amazonaws.com/2006-03-01">
2.   <CopyObjectResponse>
3.     <ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
4.     <LastModified>2008-02-18T13:54:10.183Z</LastModified>
5.   </CopyObjectResponse>
6. </CopyObjectResponse>
```

## Related Resources
<a name="SOAPCopyObject_RelatedResources"></a>
+  [PutObject (SOAP API)](SOAPPutObject.md) 
+  [PutObjectInline (SOAP API)](SOAPPutObjectInline.md) 

# GetObject (SOAP API)
<a name="SOAPGetObject"></a>

**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 AWS SDKs. 

The `GetObject` operation returns the current version of an object. If you try to `GetObject` an object that has a delete marker as its current version, S3 returns a 404 error. You cannot use the SOAP API to retrieve a specified version of an object. To do that, use the REST API. For more information, see [Versioning](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html). For more options, use the [GetObjectExtended (SOAP API)](SOAPGetObjectExtended.md) operation.

**Note**  
Object key names with the value "soap" aren't supported for [virtual-hosted-style requests](https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html#virtual-hosted-style-access). For object key name values where "soap" is used, a [path-style URL](https://docs.aws.amazon.com//AmazonS3/latest/userguide/VirtualHosting.html#path-style-access) must be used instead.

**Example**  
This example gets the "Nelson" object from the "quotes" bucket.  
`Sample Request`  

```
 1. <GetObject xmlns="http://doc.s3.amazonaws.com/2006-03-01">
 2.   <Bucket>quotes</Bucket>
 3.   <Key>Nelson</Key>
 4.   <GetMetadata>true</GetMetadata>
 5.   <GetData>true</GetData>
 6.   <InlineData>true</InlineData>
 7.   <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
 8.   <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
 9.   <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
10. </GetObject>
```
`Sample Response`  

```
 1. <GetObjectResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
 2.   <GetObjectResponse>
 3.     <Status>
 4.       <Code>200</Code>
 5.       <Description>OK</Description>
 6.     </Status>
 7.     <Metadata>
 8.       <Name>Content-Type</Name>
 9.       <Value>text/plain</Value>
10.     </Metadata>
11.     <Metadata>
12.       <Name>family</Name>
13.       <Value>Muntz</Value>
14.     </Metadata>
15.     <Data>aGEtaGE=</Data>
16.     <LastModified>2006-01-01T12:00:00.000Z</LastModified>
17.     <ETag>&quot;828ef3fdfa96f00ad9f27c383fc9ac7f&quot;</ETag>
18.   </GetObjectResponse>
19. </GetObjectResponse>
```

## Elements
<a name="SOAPGetObjectElements"></a>
+ `Bucket:` The bucket from which to retrieve the object.
+ `Key:` The key that identifies the object.
**Important**  
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.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html#object-key-xml-related-constraints).
+ `GetMetadata:` The metadata is returned with the object if this is true.
+ `GetData:` The object data is returned if this is true.
+ `InlineData:` If this is true, then the data is returned, base 64-encoded, as part of the SOAP body of the response. If false, then the data is returned as a SOAP attachment. The InlineData option is not suitable for use with large objects. The system limits this operation to working with 1MB of data or less. A GetObject request with the InlineData flag set will fail with the `InlineDataTooLargeError` status code if the resulting Data parameter would have encoded more than 1MB. To download large objects, consider calling GetObject without setting the InlineData flag, or use the REST API instead.

## Returned Elements
<a name="SOAPGetObjectReturnedElements"></a>
+ `Metadata:` The name-value paired metadata stored with the object.
+ `Data:` If InlineData was true in the request, this contains the base 64 encoded object data.
+ `LastModified:` The time that the object was stored in Amazon S3.
+ `ETag:` The object's entity tag. This is a hash of the object that can be used to do conditional gets. The ETag only reflects changes to the contents of an object, not its metadata.

## Access Control
<a name="SOAPGetObjectAccessControl"></a>

You can read an object only if you have been granted `READ` access to the object.

## SOAP Chunked and Resumable Downloads
<a name="SOAPResumableDownloads"></a>

To provide `GET` flexibility, Amazon S3 supports chunked and resumable downloads.

Select from the following:
+ For large object downloads, you might want to break them into smaller chunks. For more information, see [Range GETs](#SOAPRangeGETs) 
+ For `GET` operations that fail, you can design your application to download the remainder instead of the entire file. For more information, see [REST GET Error Recovery](#SOAPGETErrorRecovery)

### Range GETs
<a name="SOAPRangeGETs"></a>

For some clients, you might want to break large downloads into smaller downloads. To break a GET into smaller units, use Range. 

Before you can break a GET into smaller units, you must determine its size. For example, the following request gets the size of the bigfile object. 

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

Amazon S3 returns the following response.

```
 1. <ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01">
 2.   <Name>quotes</Name>
 3.   <Prefix>N</Prefix>
 4.   <MaxKeys>1</MaxKeys>
 5.   <IsTruncated>false</IsTruncated>
 6.   <Contents>
 7.     <Key>bigfile</Key>
 8.     <LastModified>2006-01-01T12:00:00.000Z</LastModified>
 9.     <ETag>&quot;828ef3fdfa96f00ad9f27c383fc9ac7f&quot;</ETag>
10.     <Size>2023276</Size>
11.     <StorageClass>STANDARD</StorageClass>
12.     <Owner>
13.       <ID>bcaf1ffd86f41161ca5fb16fd081034f</ID>
14.       <DisplayName>bigfile</DisplayName>
15.      </Owner>
16.   </Contents>
17. </ListBucketResult>
```

Following is a request that downloads the first megabyte from the bigfile object. 

```
 1. <GetObject xmlns="http://doc.s3.amazonaws.com/2006-03-01">
 2.   <Bucket>bigbucket</Bucket>
 3.   <Key>bigfile</Key>
 4.   <GetMetadata>true</GetMetadata>
 5.   <GetData>true</GetData>
 6.   <InlineData>true</InlineData>
 7.   <ByteRangeStart>0</ByteRangeStart>
 8.   <ByteRangeEnd>1048576</ByteRangeEnd>
 9.   <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
10.   <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
11.   <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
12. </GetObject>
```

Amazon S3 returns the first megabyte of the file and the Etag of the file.

```
 1. <GetObjectResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
 2.   <GetObjectResponse>
 3.     <Status>
 4.       <Code>200</Code>
 5.       <Description>OK</Description>
 6.     </Status>
 7.     <Metadata>
 8.       <Name>Content-Type</Name>
 9.       <Value>text/plain</Value>
10.     </Metadata>
11.     <Metadata>
12.       <Name>family</Name>
13.       <Value>Muntz</Value>
14.     </Metadata>
15.     <Data>--first megabyte of bigfile--</Data>
16.     <LastModified>2006-01-01T12:00:00.000Z</LastModified>
17.     <ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
18.   </GetObjectResponse>
19. </GetObjectResponse>
```

To ensure the file did not change since the previous portion was downloaded, specify the IfMatch element. Although the IfMatch element is not required, it is recommended for content that is likely to change. 

The following is a request that gets the remainder of the file, using the IfMatch request header.

```
 1. <GetObject xmlns="http://doc.s3.amazonaws.com/2006-03-01">
 2.   <Bucket>bigbucket</Bucket>
 3.   <Key>bigfile</Key>
 4.   <GetMetadata>true</GetMetadata>
 5.   <GetData>true</GetData>
 6.   <InlineData>true</InlineData>
 7.   <ByteRangeStart>10485761</ByteRangeStart>
 8.   <ByteRangeEnd>2023276</ByteRangeEnd>
 9.   <IfMatch>"828ef3fdfa96f00ad9f27c383fc9ac7f"</IfMatch>
10.   <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
11.   <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
12.   <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
13. </GetObject>
```

Amazon S3 returns the following response and the remainder of the file.

```
 1. <GetObjectResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
 2.   <GetObjectResponse>
 3.     <Status>
 4.       <Code>200</Code>
 5.       <Description>OK</Description>
 6.     </Status>
 7.     <Metadata>
 8.       <Name>Content-Type</Name>
 9.       <Value>text/plain</Value>
10.     </Metadata>
11.     <Metadata>
12.       <Name>family</Name>
13.       <Value>>Muntz</Value>
14.     </Metadata>
15.     <Data>--remainder of bigfile--</Data>
16.     <LastModified>2006-01-01T12:00:00.000Z</LastModified>
17.     <ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
18.   </GetObjectResponse>
19. </GetObjectResponse>
```

### Versioned GetObject
<a name="SOAPResumableDownloads-versioned-getobject"></a>

The following request returns the specified version of the object in the bucket. 

```
 1. <GetObject xmlns="http://doc.s3.amazonaws.com/2006-03-01">
 2. <Bucket>quotes</Bucket>
 3. <Key>Nelson</Key>
 4. <GetMetadata>true</GetMetadata>
 5. <GetData>true</GetData>
 6. <InlineData>true</InlineData>
 7. <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
 8. <Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
 9. <Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
10. </GetObject>
```

Sample Response

```
 1. <GetObjectResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
 2. <GetObjectResponse>
 3. <Status>
 4. <Code>200</Code>
 5. <Description>OK</Description>
 6. </Status>
 7. <Metadata>
 8. <Name>Content-Type</Name>
 9. <Value>text/plain</Value>
10. </Metadata>
11. <Metadata>
12. <Name>family</Name>
13. <Value>Muntz</Value>
14. </Metadata>
15. <Data>aGEtaGE=</Data>
16. <LastModified>2006-01-01T12:00:00.000Z</LastModified>
17. <ETag>&quot;828ef3fdfa96f00ad9f27c383fc9ac7f&quot;</ETag>
18. </GetObjectResponse>
19. </GetObjectResponse>
```

### REST GET Error Recovery
<a name="SOAPGETErrorRecovery"></a>

If an object GET fails, you can get the rest of the file by specifying the range to download. To do so, you must get the size of the object using `ListBucket` and perform a range `GET` on the remainder of the file. For more information, see [GetObjectExtended (SOAP API)](SOAPGetObjectExtended.md).

### Related Resources
<a name="SOAPGettingObjectsRelatedTopics"></a>

[Operations on Objects (SOAP API)](SOAPObjectsOps.md)

# GetObjectExtended (SOAP API)
<a name="SOAPGetObjectExtended"></a>

**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 AWS SDKs. 

`GetObjectExtended` is exactly like [GetObject (SOAP API)](SOAPGetObject.md), except that it supports the following additional elements that can be used to accomplish much of the same functionality provided by HTTP GET headers (go to [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)).

GetObjectExtended supports the following elements in addition to those supported by GetObject:
+ `ByteRangeStart, ByteRangeEnd:` These elements specify that only a portion of the object data should be retrieved. They follow the behavior of the HTTP byte ranges (go to [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html\$1sec14.35](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35)).
+ `IfModifiedSince:` Return the object only if the object's timestamp is later than the specified timestamp. ([http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html\$1sec14.25](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.25))
+ `IfUnmodifiedSince:` Return the object only if the object's timestamp is earlier than or equal to the specified timestamp. (go to [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html\$1sec14.28](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.28))
+ `IfMatch:` Return the object only if its ETag matches the supplied tag(s). (go to [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html\$1sec14.24](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.24))
+ `IfNoneMatch:` Return the object only if its ETag does not match the supplied tag(s). (go to [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html\$1sec14.26](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.26))
+ `ReturnCompleteObjectOnConditionFailure:`ReturnCompleteObjectOnConditionFailure: If true, then if the request includes a range element and one or both of IfUnmodifiedSince/IfMatch elements, and the condition fails, return the entire object rather than a fault. This enables the If-Range functionality (go to [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html\$1sec14.27](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.27)).

# DeleteObject (SOAP API)
<a name="SOAPDeleteObject"></a>

**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 AWS SDKs. 

The `DeleteObject` operation removes the specified object from Amazon S3. Once deleted, there is no method to restore or undelete an object.

**Note**  
If you delete an object that does not exist, Amazon S3 will return a success (not an error message). 

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

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

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

## Elements
<a name="SOAPDeleteObjectElements"></a>
+ `Bucket:` The bucket that holds the object.
+ `Key:` The key that identifies the object.
**Important**  
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.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html#object-key-xml-related-constraints).

## Access Control
<a name="SOAPDeleteObjectAccessControl"></a>

You can delete an object only if you have `WRITE` access to the bucket, regardless of who owns the object or what rights are granted to it. 

# GetObjectAccessControlPolicy (SOAP API)
<a name="SOAPGetObjectAccessControlPolicy"></a>

**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 AWS SDKs. 

The `GetObjectAccessControlPolicy` operation fetches the access control policy for an object.

**Important**  
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.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html#object-key-xml-related-constraints).

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

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

```
 1. <AccessControlPolicy>
 2.   <Owner>
 3.     <ID>a9a7b886d6fd24a541bf9b1c61be666e9</ID>
 4.     <DisplayName>chriscustomer</DisplayName>
 5.   </Owner>
 6.   <AccessControlList>
 7.     <Grant>
 8.       <Grantee xsi:type="CanonicalUser">
 9.         <ID>a9a7b841bf9b1c61be666e9</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
<a name="SOAPGetObjectAccessControlPolicyResponseBody"></a>

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

## Access Control
<a name="SOAPGetObjectAccessControlPolicyAccessControl"></a>

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

# SetObjectAccessControlPolicy (SOAP API)
<a name="SOAPSetObjectAccessControlPolicy"></a>

**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 AWS SDKs. 

The `SetObjectAccessControlPolicy` operation sets the access control policy for an existing object. If successful, the previous access control policy for the object is entirely replaced with the specified access control policy.

**Example**  
This example gives the specified user (usually the owner) `FULL_CONTROL` access to the "Nelson" object from the "quotes" bucket.  
`Sample Request`  

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

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

## Key
<a name="SOAPSetObjectAccessControlPolicyKey"></a>

**Important**  
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.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html#object-key-xml-related-constraints).

## Access Control
<a name="SOAPSetObjectAccessControlPolicyAccessControl"></a>

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