GET Object

Description

You fetch objects from Amazon S3 using the GET operation. This operation returns objects directly from Amazon S3 using a client/server delivery mechanism.

To distribute large files to many people, you can save bandwidth costs by using BitTorrent. For more information, see Using BitTorrent with Amazon S3.

	Note
	To use `GET`, you must have `READ` access to the object. If `READ` access is granted to the anonymous user, you can request the object without an authorization header.

Requests

Syntax

GET /destinationObject HTTP/1.1
Host: destinationBucket.s3.amazonaws.com
Date: date
Authorization: signature
Range:bytes=byte_range

Headers

Name	Description	Required
`Range`	Downloads the specified range of an object. 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

Responses

Success Response

Syntax

HTTP/1.1 200 OK
x-amz-id-2: id
x-amz-request-id: request_id
Date: date
Last-Modified: Sun, 1 Jan 2006 12:00:00 GMT
ETag: "etag"
Content-Length: length
Content-Type: type
Connection: close
Server: AmazonS3

file_content

Elements

Name	Description
`x-amz-meta-`	If you supplied user metadata when you `PUT` the object, that metadata is returned in one or more response headers prefixed with x-amz-meta- and with the suffix name that you provided on storage. This metadata is simply returned verbatim; it is not interpreted by Amazon S3. Type: String
`Content-Type`	This is set to the same value you specified in the corresponding header when the data was `PUT`. The default content type is binary/octet-stream. Type: String
`Content-Disposition`	This is set to the same value you specified in the corresponding header when the data was `PUT`. Except in the case of a request for a BitTorrent torrent file, if no Content-Disposition was specified at the time of `PUT` then this header is not returned. For more information about BitTorrent, see Using BitTorrent with Amazon S3. Type: String
`Content-Range`	This indicates the range of bytes returned in the event that you requested a subset of the object by setting the Range request header. Type: String
`x-amz-missing-meta`	This is set to the number of metadata entries not returned in x-amz-meta headers. This can happen if you create metadata using an API like SOAP that supports more flexible metadata than the REST API. For example, using SOAP, you can create metadata whose values are not legal HTTP headers. Type: String
`Etag`	Returns the Etag of the new object. Type: String

Special Errors

There are no special errors for this operation. For information about general Amazon S3 errors, see List of Error Codes.

Examples

Sample Request

This example retrieves the "Nelson" object and its metadata from the "quotes" bucket.

GET /Nelson HTTP/1.1
Host: quotes.s3.amazonaws.com
Date: Wed, 01 Mar  2006 12:00:00 GMT
Authorization: AWS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE=

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: j5ULAWpFbJQJpukUsZ4tfXVOjVZExLtEyNTvY5feC+hHIegsN5p578JLTVpkFrpL
x-amz-request-id: BE39A20848A0D52B
Date: Wed, 01 Mar  2006 12:00:00 GMT
x-amz-meta-family: Muntz
Last-Modified: Sun, 1 Jan 2006 12:00:00 GMT
ETag: "828ef3fdfa96f00ad9f27c383fc9ac7f"
Content-Type: text/plain
Content-Length: 5
Connection: close
Server: AmazonS3

HA-HA

Range GET Sample Request

For some clients, you might want to break large downloads into smaller downloads. To break a download into smaller units, use Range. For example, the following request downloads the first ten megabytes from the bigfile object.

GET /bigfile HTTP/1.1
Host: bigbucket.s3.amazonaws.com
Date: Wed, 01 Mar  2006 12:00:00 GMT
Authorization: AWS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE=
Range:bytes=0-10485759

Range GET Sample Response

HTTP/1.1 206 Partial Content
x-amz-id-2: j5ULAWpFbJQJpukUsZ4tfXVOjVZExLtEyNTvY5feC+hHIegsN5p578JLTVpkFrpL
x-amz-request-id: BE39A20848A0D52B
Date: Wed, 01 Mar  2006 12:00:00 GMT
x-amz-meta-family: Muntz
Last-Modified: Sun, 1 Jan 2006 12:00:00 GMT
ETag: "828ef3fdfa96f00ad9f27c383fc9ac7f"
Content-Type: text/plain
Content-Length: 10485760
Content-Range: 0-10485759/20232760
Connection: close
Server: AmazonS3

<first 10 megabytes of bigfile>

Amazon S3 returns the first ten megabytes of the file, the Etag of the file, and the total size of the file (20232760 bytes) in the Content-Length field.

To ensure the file did not change since the previous portion was downloaded, specify the if-match request header. Although the if-match request header is not required, it is recommended for content that is likely to change.

	Note
	If the you specify `if-match` for a partial `GET` and the Etag does not match, you must perform a subsequent `GET` to download the object. To construct your request to get the entire object if the Etag does not match, add the `if-range` request header to the request. For more information, go to Section 14.27 of RFC 2616.

Second Range GET Sample Request

Following is a request that gets the remainder of the file, using the if-match request header.

GET /bigfile HTTP/1.1
Host: bigbucket.s3.amazonaws.com
Date: Wed, 01 Mar  2006 12:00:00 GMT
Authorization: AWS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE=
Range: 10485760-20232760
If-match:"828ef3fdfa96f00ad9f27c383fc9ac7f"

Second Range GET Sample Response

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

x-amz-id-2: j5ULAWpFbJQJpukUsZ4tfXVOjVZExLtEyNTvY5feC+hHIegsN5p578JLTVpkFrpL
x-amz-request-id: BE39A20848A0D52B
Date: Wed, 01 Mar  2006 12:00:00 GMT
x-amz-meta-family: Muntz
Last-Modified: Sun, 1 Jan 2006 12:00:00 GMT
ETag: "828ef3fdfa96f00ad9f27c383fc9ac7f"
Content-Type: text/plain
Content-Length: 9747000
Content-Range: 10485760-20232760/20232760
Connection: close
Server: AmazonS3

<remainder of bigfile>

REST GET Error Recovery Sample Request

If an object GET fails, you can get the rest of the file by specifying the range to download. The following is a standard GET for the bigfile object.

GET /bigfile HTTP/1.1
Host: bigbucket.s3.amazonaws.com
Date: Wed, 01 Mar  2006 12:00:00 GMT
Authorization: AWS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE=

REST GET Error Recovery Sample Response

Amazon S3 returns the following response, but a client connection issue causes the GET to fail in the middle of the operation.

HTTP/1.1 200 OK
x-amz-id-2: j5ULAWpFbJQJpukUsZ4tfXVOjVZExLtEyNTvY5feC+hHIegsN5p578JLTVpkFrpL
x-amz-request-id: BE39A20848A0D52B
Date: Wed, 01 Mar  2006 12:00:00 GMT
x-amz-meta-family: Muntz
Last-Modified: Sun, 1 Jan 2006 12:00:00 GMT
ETag: "828ef3fdfa96f00ad9f27c383fc9ac7f"
Content-Type: text/plain
Content-Length: 20232760
Connection: close
Server: AmazonS3

<part of bigfile>

Second REST GET Error Recovery Sample Request

The client code determines the amount of data downloaded and gets the rest.

GET /bigfile HTTP/1.1
Host: bigbucket.s3.amazonaws.com
Date: Wed, 01 Mar  2006 12:00:00 GMT
Authorization: AWS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE=
Range:bytes=132499-20232760
If-match:"828ef3fdfa96f00ad9f27c383fc9ac7f"

Second REST GET Error Recovery Sample Response

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

HTTP/1.1 206 Partial Content
x-amz-id-2: j5ULAWpFbJQJpukUsZ4tfXVOjVZExLtEyNTvY5feC+hHIegsN5p578JLTVpkFrpL
x-amz-request-id: BE39A20848A0D52B
Date: Wed, 01 Mar  2006 12:00:00 GMT
x-amz-meta-family: Muntz
Last-Modified: Sun, 1 Jan 2006 12:00:00 GMT
ETag: "828ef3fdfa96f00ad9f27c383fc9ac7f"
Content-Type: text/plain
Content-Length: 20100261
Content-Range: 132499-20232760/20232760
Connection: close
Server: AmazonS3

<remainder of bigfile>

Related Resources

GET Service