Amazon Simple Storage Service
API Reference (API Version 2006-03-01)
Did this page help you?  Yes | No |  Tell us about it...
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.

GET Object

Description

This implementation of the GET operation retrieves objects from Amazon S3. To use GET, you must have READ access to the object. If you grant READ access to the anonymous user, you can return the object without using an authorization header.

An Amazon S3 bucket has no directory hierarchy such as you would find in a typical computer file system. You can, however, create a logical hierarchy by using object key names that imply a folder structure. For example, instead of naming an object sample.jpg, you can name it photos/2006/February/sample.jpg.

To get an object from such a logical hierarchy, specify the full key name for the object in the GET operation. For a virtual hosted-style request example, if you have the object photos/2006/February/sample.jpg, specify the resource as /photos/2006/February/sample.jpg. For a path-style request example, if you have the object photos/2006/February/sample.jpg in the bucket named examplebucket, specify the resource as /examplebucket/photos/2006/February/sample.jpg. For more information about request types, see HTTP Host Header Bucket Specification in the Amazon Simple Storage Service Developer Guide.

To distribute large files to many people, you can save bandwidth costs by using BitTorrent. For more information, see Amazon S3 Torrent in the Amazon Simple Storage Service Developer Guide. For more information about returning the ACL of an object, see GET Object ACL.

If the object you are retrieving is a GLACIER storage class object, the object is archived in Amazon Glacier. You must first restore a copy using the POST Object restore API before you can retrieve the object. Otherwise, this operation returns an InvalidObjectStateError error. For information about archiving objects in Amazon Glacier, go to Object Lifecycle Management in the Amazon Simple Storage Service Developer Guide.

If you encrypt an object by using server-side encryption with customer-provided encryption keys (SSE-C) when you store the object in Amazon S3, then when you GET the object, you must use the headers documented in the section Specific Request Headers for Server-Side Encryption with Customer-Provided Encryption Keys . For more information about SSE-C, go to Server-Side Encryption (Using Customer-Provided Encryption Keys) in the Amazon Simple Storage Service Developer Guide.

Permissions

You need the s3:GetObject permission for this operation.  For more information, go to Specifying Permissions in a Policy in the Amazon Simple Storage Service Developer Guide. If the object you request does not exist, the error Amazon S3 returns depends on whether you also have the s3:ListBucket permission.

  • If you have the s3:ListBucket permission on the bucket, Amazon S3 will return an HTTP status code 404 ("no such key") error.

  • if you don’t have the s3:ListBucket permission, Amazon S3 will return an HTTP status code 403 ("access denied") error.

Versioning

By default, the GET operation returns the current version of an object. To return a different version, use the versionId subresource.

Note

If the current version of the object is a delete marker, Amazon S3 behaves as if the object was deleted and includes x-amz-delete-marker: true in the response.

For more information about versioning, see PUT Bucket versioning To see sample requests that use versioning, see Sample Request Getting a Specified Version of an Object .

Requests

Syntax

GET /ObjectName HTTP/1.1
Host: BucketName.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version 4))
Range:bytes=byte_range

Request Parameters

There are times when you want to override certain response header values in a GET response. For example, you might override the Content-Disposition response header value in your GET request.

You can override values for a set of response headers using the query parameters listed in the following table. These response header values are sent only on a successful request, that is, when status code 200 OK is returned. The set of headers you can override using these parameters is a subset of the headers that Amazon S3 accepts when you create an object. The response headers that you can override for the GET response are Content-Type, Content-Language, Expires, Cache-Control, Content-Disposition, and Content-Encoding. To override these header values in the GET response, you use the request parameters described in the following table.

Note

You must sign the request, either using an Authorization header or a pre-signed URL, when using these parameters. They cannot be used with an unsigned (anonymous) request.

ParameterDescriptionRequired
response-content-type

Sets the Content-Type header of the response.

Type: String

Default: None

No
response-content-language

Sets the Content-Language header of the response.

Type: String

Default: None

No
response-expires

Sets the Expires header of the response.

Type: String

Default: None

No
response-cache-control

Sets the Cache-Control header of the response.

Type: String

Default: None

No
response-content-disposition

Sets the Content-Disposition header of the response.

Type: String

Default: None

No
response-content-encoding

Sets the Content-Encoding header of the response.

Type: String

Default: None

No

Request Headers

This implementation of the operation can use the following request headers in addition to the request headers common to all operations. For more information, see Common Request Headers.

Name Description Required
Range

Downloads the specified range bytes of an object. For more information about the HTTP Range header, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35.

Type: String

Default: None

Constraints: None

No
If-Modified-Since

Return the object only if it has been modified since the specified time, otherwise return a 304 (not modified).

Type: String

Default: None

Constraints: None

No
If-Unmodified-Since

Return the object only if it has not been modified since the specified time, otherwise return a 412 (precondition failed).

Type: String

Default: None

Constraints: None

No
If-Match

Return the object only if its entity tag (ETag) is the same as the one specified; otherwise, return a 412 (precondition failed).

Type: String

Default: None

Constraints: None

No
If-None-Match

Return the object only if its entity tag (ETag) is different from the one specified; otherwise, return a 304 (not modified).

Type: String

Default: None

Constraints: None

No

Specific Request Headers for Server-Side Encryption with Customer-Provided Encryption Keys

When you retrieve an object from Amazon S3 that was encrypted by using server-side encryption with customer-provided encryption keys (SSE-C), you must use the following request headers. For more information about SSE-C, go to Server-Side Encryption (Using Customer-Provided Encryption Keys) in the Amazon Simple Storage Service Developer Guide.

Name Description Required
x-amz-server-side​-encryption​-customer-algorithm

Specifies the algorithm to use to when decrypting the requested object.

Type: String

Default: None

Valid Values: AES256

Constraints: Must be accompanied by valid x-amz-server-side-encryption-customer-key and x-amz-server-side-encryption-customer-key-MD5 headers.

Yes
x-amz-server-side​-encryption​-customer-key

Specifies the customer-provided base64-encoded encryption key to use to decrypt the requested object. This value is used to perform the decryption and then it is discarded; Amazon does not store the key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side​-encryption​-customer-algorithm header.

Type: String

Default: None

Constraints: Must be accompanied by valid x-amz-server-side-encryption-customer-algorithm and x-amz-server-side-encryption-customer-key-MD5 headers.

Yes
x-amz-server-side​-encryption​-customer-key-MD5

Specifies the base64-encoded 128-bit MD5 digest of the customer-provided encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure that the encryption key was transmitted without error.

Type: String

Default: None

Constraints: Must be accompanied by valid x-amz-server-side-encryption-customer-algorithm and x-amz-server-side-encryption-customer-key headers.

Yes

Request Elements

This implementation of the operation does not use request elements.

Responses

Response Headers

HeaderDescription
x-amz-delete-marker

Specifies whether the object retrieved was (true) or was not (false) a delete marker. If false, this response header does not appear in the response.

Type: Boolean

Valid Values: true | false

Default: false

x-amz-expiration

Amazon S3 returns this header if an Expiration action is configured for the object as part of the bucket's lifecycle configuration.  The header value includes an "expiry-date" component and a URL-encoded "rule-id" component.  Note that for versioning-enabled buckets, this header applies only to current versions; Amazon S3 does not provide a header to infer when a noncurrent version will be eligible for permanent deletion. For more information, see PUT Bucket lifecycle.

Type: String

x-amz-server-side​-encryption

If the object is stored using server-side encryption either with an AWS KMS or an Amazon S3-managed encryption key, the response includes this header with the value of the encryption algorithm used.

Type: String

x-amz-server-side-encryption-aws-kms-key-id

If the x-amz-server-side-encryption is present and has the value of aws:kms, this header specifices the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.

Type: String

x-amz-server-side​-encryption​-customer-algorithm

If server-side encryption with customer-provided encryption keys decryption was requested, the response will include this header confirming the decryption algorithm used.

Type: String

Valid Values: AES256

x-amz-server-side​-encryption​-customer-key-MD5

If server-side encryption with customer-provided encryption keys decryption was requested, the response includes this header to provide roundtrip message integrity verification of the customer-provided encryption key.

Type: String

x-amz-restore

Provides information about the object restoration operation and expiration time of the restored object copy.

For more information about archiving objects and restoring them, go to Object Lifecycle Management in Amazon Simple Storage Service Developer Guide

Type: String

Default: None

x-amz-version-id

Returns the version ID of the retrieved object if it has a unique version ID.

Type: String

Default: None

x-amz-website​-redirect-location

When a bucket is configured as a website, you can set this metadata on the object so the website endpoint will evaluate the request for the object as a 301 redirect to another object in the same bucket or an external URL.

Type: String

Default: None

Response Elements

This implementation of the operation does not return response elements.

Special Errors

This implementation of the operation does not return special errors. For general information about Amazon S3 errors and a list of error codes, see Error Responses.

Examples

Sample Request

The following request returns the object, my-image.jpg.

GET /my-image.jpg HTTP/1.1
Host: bucket.s3.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: authorization string

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: eftixk72aD6Ap51TnqcoF8eFidJG9Z/2mkiDFu8yU9AS1ed4OpIszj7UDNEHGran
x-amz-request-id: 318BC8BC148832E5
Date: Wed, 28 Oct 2009 22:32:00 GMT
Last-Modified: Wed, 12 Oct 2009 17:50:00 GMT
ETag: "fba9dede5f27731c9771645a39863328"
Content-Length: 434234
Content-Type: text/plain
Connection: close
Server: AmazonS3
[434234 bytes of object data]

If the object had expiration set using lifecycle configuration, you get the following response with the x-amz-expiration header.

HTTP/1.1 200 OK
x-amz-id-2: eftixk72aD6Ap51TnqcoF8eFidJG9Z/2mkiDFu8yU9AS1ed4OpIszj7UDNEHGran
x-amz-request-id: 318BC8BC148832E5
Date: Wed, 28 Oct 2009 22:32:00 GMT
Last-Modified: Wed, 12 Oct 2009 17:50:00 GMT
x-amz-expiration: expiry-date="Fri, 23 Dec 2012 00:00:00 GMT", rule-id="picture-deletion-rule"
ETag: "fba9dede5f27731c9771645a39863328"
Content-Length: 434234
Content-Type: text/plain
Connection: close
Server: AmazonS3
[434234 bytes of object data]

Sample Response if an Object Is Archived in Amazon Glacier

An object archived in Amazon Glacier must first be restored before you can access it. If you attempt to access an Amazon Glacier object without restoring it, Amazon S3 returns the following error.

HTTP/1.1 403 Forbidden
x-amz-request-id: CD4BD8A1310A11B3
x-amz-id-2: m9RDbQU0+RRBTjOUN1ChQ1eqMUnr9dv8b+KP6I2gHfRJZSTSrMCoRP8RtPRzX9mb
Content-Type: application/xml
Date: Mon, 12 Nov 2012 23:53:21 GMT
Server: AmazonS3
Content-Length: 231

<Error>
   <Code>InvalidObjectState</Code>
   <Message>The operation is not valid for the object's storage class</Message>
   <RequestId>9FEFFF118E15B86F</RequestId>
   <HostId>WVQ5kzhiT+oiUfDCOiOYv8W4Tk9eNcxWi/MK+hTS/av34Xy4rBU3zsavf0aaaaa</HostId>
</Error>

Sample Response if the Latest Object Is a Delete Marker

HTTP/1.1 404 Not Found
x-amz-request-id: 318BC8BC148832E5
x-amz-id-2: eftixk72aD6Ap51Tnqzj7UDNEHGran
x-amz-version-id: 3GL4kqtJlcpXroDTDm3vjVBH40Nr8X8g
x-amz-delete-marker:  true
Date: Wed, 28 Oct 2009 22:32:00 GMT
Content-Type: text/plain
Connection: close
Server: AmazonS3

Notice that the delete marker returns a 404 Not Found error.

Sample Request Getting a Specified Version of an Object

The following request returns the specified version of an object.

GET /myObject?versionId=3/L4kqtJlcpXroDTDmpUMLUo HTTP/1.1
Host: bucket.s3.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: authorization string

Sample Response to a Versioned Object GET Request

HTTP/1.1 200 OK
x-amz-id-2: eftixk72aD6Ap54OpIszj7UDNEHGran
x-amz-request-id: 318BC8BC148832E5
Date: Wed, 28 Oct 2009 22:32:00 GMT
Last-Modified: Sun, 1 Jan 2006 12:00:00 GMT
x-amz-version-id: 3/L4kqtJlcpXroDTDmJ+rmSpXd3QBpUMLUo
ETag: "fba9dede5f27731c9771645a39863328"
Content-Length: 434234
Content-Type: text/plain
Connection: close
Server: AmazonS3
[434234 bytes of object data]

Sample Request with Parameters Altering Response Header Values

The following request specifies all the query string parameters in a GET request overriding the response header values.

GET /Junk3.txt?response-cache-control=No-cache&response-content-disposition=attachment%3B%20filename%3Dtesting.txt&response-content-encoding=x-gzip&response-content-language=mi%2C%20en&response-expires=Thu%2C%2001%20Dec%201994%2016:00:00%20GMT HTTP/1.1
x-amz-date: Sun, 19 Dec 2010 01:53:44 GMT
Accept: */*
Authorization: AWS AKIAIOSFODNN7EXAMPLE:aaStE6nKnw8ihhiIdReoXYlMamW=

Sample Response with Overridden Response Header Values

In the following sample response note, the header values are set to the values specified in the true request.

HTTP/1.1 200 OK
x-amz-id-2: SIidWAK3hK+Il3/Qqiu1ZKEuegzLAAspwsgwnwygb9GgFseeFHL5CII8NXSrfWW2
x-amz-request-id: 881B1CBD9DF17WA1
Date: Sun, 19 Dec 2010 01:54:01 GMT
x-amz-meta-param1: value 1
x-amz-meta-param2: value 2
Cache-Control: No-cache
Content-Language: mi, en
Expires: Thu, 01 Dec 1994 16:00:00 GMT
Content-Disposition: attachment; filename=testing.txt
Content-Encoding: x-gzip
Last-Modified: Fri, 17 Dec 2010 18:10:41 GMT
ETag: "0332bee1a7bf845f176c5c0d1ae7cf07"
Accept-Ranges: bytes
Content-Type: text/plain
Content-Length: 22
Server: AmazonS3

[object data not shown]

Sample Request with a Range Header

The following request specifies the HTTP Range header to retrieve the first 10 bytes of an object. For more information about the HTTP Range header, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.

GET /example-object HTTP/1.1
Host: example-bucket.s3.amazonaws.com
x-amz-date: Fri, 28 Jan 2011 21:32:02 GMT
Range: bytes=0-9
Authorization: AWS AKIAIOSFODNN7EXAMPLE:Yxg83MZaEgh3OZ3l0rLo5RTX11o=
Sample Response with Specified Range of the Object Bytes

Sample Response

In the following sample response, note that the header values are set to the values specified in the true request.

HTTP/1.1 206 Partial Content
x-amz-id-2: MzRISOwyjmnupCzjI1WC06l5TTAzm7/JypPGXLh0OVFGcJaaO3KW/hRAqKOpIEEp
x-amz-request-id: 47622117804B3E11
Date: Fri, 28 Jan 2011 21:32:09 GMT
x-amz-meta-title: the title
Last-Modified: Fri, 28 Jan 2011 20:10:32 GMT
ETag: "b2419b1e3fd45d596ee22bdf62aaaa2f"
Accept-Ranges: bytes
Content-Range: bytes 0-9/443
Content-Type: text/plain
Content-Length: 10
Server: AmazonS3

[10 bytes of object data]

Sample: Get an Object Stored Using Server-Side Encryption with Customer-Provided Encryption Keys

If an object is stored in Amazon S3 using server-side encryption with customer-provided encryption keys, Amazon S3 needs encryption information so that it can decrypt the object before sending it to you in response to a GET request. You provide the encryption information in your GET request using the relevant headers (see Specific Request Headers for Server-Side Encryption with Customer-Provided Encryption Keys ), as shown in the following example request.

GET /example-object HTTP/1.1
Host: example-bucket.s3.amazonaws.com	

Accept: */*
Authorization:authorization string   
Date: Wed, 28 May 2014 19:24:44 +0000   
x-amz-server-side-encryption-customer-key:g0lCfA3Dv40jZz5SQJ1ZukLRFqtI5WorC/8SEKEXAMPLE   
x-amz-server-side-encryption-customer-key-MD5:ZjQrne1X/iTcskbY2m3example  
x-amz-server-side-encryption-customer-algorithm:AES256     

The following sample response shows some of the response headers Amazon S3 returns. Note that it includes the encryption information in the response.

HTTP/1.1 200 OK
x-amz-id-2: ka5jRm8X3N12ZiY29Z989zg2tNSJPMcK+to7jNjxImXBbyChqc6tLAv+sau7Vjzh
x-amz-request-id: 195157E3E073D3F9   
Date: Wed, 28 May 2014 19:24:45 GMT   
Last-Modified: Wed, 28 May 2014 19:21:01 GMT   
ETag: "c12022c9a3c6d3a28d29d90933a2b096"   
x-amz-server-side-encryption-customer-algorithm: AES256   
x-amz-server-side-encryption-customer-key-MD5: ZjQrne1X/iTcskbY2m3example