The Wayback Machine - https://web.archive.org/web/20190711121119/https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectGET.html
Sign In to the Console
Amazon Simple Storage Service
API Reference (API Version 2006-03-01)

AWS Documentation » Amazon Simple Storage Service (S3) » API Reference » Operations on Objects » GET Object

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 stored in the GLACIER or DEEP_ARCHIVE storage classes, before you can retrieve the object you must first restore a copy using the POST Object restore API. Otherwise, this operation returns an InvalidObjectStateError error. For information about restoring archived objects, see Restoring Archived Objects 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.

Assuming you have permission to read object tags (permission for the s3:GetObjectVersionTagging action), the response also returns the x-amz-tagging-count header that provides the count of number of tags associated with the object. You can use the "GET Object tagging" API (see GET Object tagging) to retrieve the tag set associated with an object.

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

Parameter Description Required
partNumber

Part number of the object part being read. This is a positive integer between 1 and the maximum number of parts supported.

Only objects uploaded using the multipart upload API have part numbers. For information about multipart uploads, see Multipart Upload Overview in the Amazon Simple Storage Service Developer Guide.

Effectively performs a 'ranged' GET request for the part specified. Useful for downloading just a part of an object.

Type: Integer

Default: None

 No
versionId

Version ID used to reference a specific version of the object.

Type: String

Default: None

 No

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 presigned URL, when using these parameters. They cannot be used with an unsigned (anonymous) request.

Parameter Description Required
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. Request headers are limited to 8 KB in size. 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).

See Consideration 2 after the table.

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).

See Consideration 1 after the table.

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).

See Consideration 1 after the table.

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).

See Consideration 2 after the table.

Type: String

Default: None

Constraints: None

 No

Note

Encryption request headers, like x-amz-server-side-encryption, should not be sent for GET requests if your object uses server-side encryption with AWS KMS–managed encryption keys (SSE-KMS) or server-side encryption with Amazon S3–managed encryption keys (SSE-S3). If your object does use these types of keys, you’ll get an HTTP 400 BadRequest error.

Note the following additional considerations about the preceding request headers:

  • Consideration 1 – If both of the If-Match and If-Unmodified-Since headers are present in the request as follows:

    If-Match condition evaluates to true, and;

    If-Unmodified-Since condition evaluates to false;

    then, S3 returns 200 OK and the data requested. For more information about conditional requests, see RFC 7232.

     

  • Consideration 2 – If both of the If-None-Match and If-Modified-Since headers are present in the request as follows:

    If-None-Match condition evaluates to false, and;

    If-Modified-Since condition evaluates to true;

    then, S3 returns 304 Not Modified response code. For more information about conditional requests, see RFC 7232.

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. If this header is included in your request, Amazon S3 uses it 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.

No

Request Elements

This implementation of the operation does not use request elements.

Responses

Response Headers

Header Description
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-meta-*

Headers starting with this prefix are user-defined metadata. Each one is stored and returned as a set of key-value pairs. Amazon S3 doesn't validate or interpret user-defined metadata.

Type: String
x-amz-replication-status

Amazon S3 can return this header if your request involves a bucket that is either a source or destination in a cross-region replication.

In cross-region replication you have a source bucket on which you configure replication and destination bucket where Amazon S3 stores object replicas. When you request an object (GET Object) or object metadata (HEAD Object) from these buckets, Amazon S3 will return the x-amz-replication-status header in the response as follow:

  • If requesting object from the source bucket — Amazon S3 will return the x-amz-replication-status header if object in your request is eligible for replication.

    For example, suppose in your replication configuration you specify object prefix "TaxDocs" requesting Amazon S3 to replicate objects with key prefix "TaxDocs". Then any objects you upload with this key name prefix, for example "TaxDocs/document1.pdf", is eligible for replication. For any object request with this key name prefix Amazon S3 will return the x-amz-replication-status header with value PENDING, COMPLETED or FAILED indicating object replication status.

  • If requesting object from the destination bucket — Amazon S3 will return the x-amz-replication-status header with value REPLICA if object in your request is a replica that Amazon S3 created.

For more information, go to Cross-Region Replication in the Amazon Simple Storage Service Developer Guide.

Valid Values: PENDING, COMPLETED, FAILED, REPLICA

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 specifies 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-storage-class

Provides storage class information of the object. Amazon S3 returns this header for all objects except for Standard storage class objects.

For more information, go to Storage Classes in Amazon Simple Storage Service Developer Guide.

Type: String

Default: None
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 Transitioning Objects: General Considerations in the Amazon Simple Storage Service Developer Guide.

Type: String

Default: None
x-amz-tagging-count

Returns the count of the tags associated with the object. This header is returned only if the count is greater than zero.

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
x-amz-object-lock-mode The Object Lock mode, if any, that's in effect for this object. This header is only returned if the requester has the s3:GetObjectRetention permission. For more information about S3 Object Lock, see Object Lock in the Amazon Simple Storage Service Developer Guide.

Type: String

Valid values: GOVERNANCE | COMPLIANCE
x-amz-object-lock-retain-until-date The date and time when the Object Lock retention period expires. This header is only returned if the requester has the s3:GetObjectRetention permission.

Type: Timestamp

Format: 2020-01-05T00:00:00.000Z
x-amz-object-lock-legal-hold Specifies whether a legal hold is in effect for this object. This header is only returned if the requester has the s3:GetObjectLegalHold permission. This header is not returned if the specified version of this object has never had a legal hold applied. For more information about legal holds, see Object Lock in the Amazon Simple Storage Service Developer Guide.

Type: String

Valid values: ON | OFF

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: Mon, 3 Oct 2016 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: Mon, 3 Oct 2016 22:32:00 GMT
Last-Modified: Wed, 12 Oct 2009 17:50:00 GMT
ETag: "fba9dede5f27731c9771645a39863328"
Content-Length: 434234

[434234 bytes of object data]

If the object had tags associated with it, Amazon S3 returns the x-amz-tagging-count header with tag count. 

HTTP/1.1 200 OK
x-amz-id-2: eftixk72aD6Ap51TnqcoF8eFidJG9Z/2mkiDFu8yU9AS1ed4OpIszj7UDNEHGran
x-amz-request-id: 318BC8BC148832E5
Date: Mon, 3 Oct 2016 22:32:00 GMT
Last-Modified: Wed, 12 Oct 2009 17:50:00 GMT
ETag: "fba9dede5f27731c9771645a39863328"
Content-Length: 434234
x-amz-tagging-count: 2

[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

[434234 bytes of object data]

Sample Response if an Object Is Archived in Glacier

An object archived in Glacier must first be restored before you can access it. If you attempt to access an 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 for Getting an Object Part

The following request returns the specified part of the object test.txt. 

GET /test.txt?partNumber=1 HTTP/1.1
Host: bucket.s3.amazonaws.com
Date: Mon, 3 Oct 2016 22:32:00 GMT
Authorization: authorization string

Sample Response to an Object Part Request 

HTTP/1.1 206 Partial Content
x-amz-id-2: 4lJovnctP+tyF27MwR7pAg0Y9Jgf0AVAL+pOhyJlWM4yCxwdbnilC/BlSVFxbmzIvjtgTPqLDrU=
x-amz-request-id: 8AC212BBF9DF3D33
Date: Thu, 28 Jun 2018 20:11:04 GMT
Last-Modified: Thu, 28 Jun 2018 19:16:25 GMT
ETag: "497db513b7b597ec93459bd2f3c9a452"
x-amz--mp-parts-count: 6
Accept-Ranges: bytes
Content-Range: bytes 0-121443838/876536789
Content-Type: binary/octet-stream
Content-Length: 121443839

[121443839 bytes of object data]

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

Note

Amazon S3 doesn't support retrieving multiple ranges of data per GET request.

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