AWS Documentation » Amazon Simple Storage Service (S3) » API Reference » REST API » Operations on Objects » HEAD Object	« Previous Next »
	Did this page help you? Yes \| No \| Tell us about it...

HEAD Object

Description

The HEAD operation retrieves metadata from an object without returning the object itself. This operation is useful if you are interested only in an object's metadata. To use HEAD, you must have READ access to the object.

A HEAD request has the same options as a GET operation on an object. The response is identical to the GET response except that there is no response body.

Requests

Syntax

HEAD /ObjectName HTTP/1.1
Host: BucketName.s3.amazonaws.com
Authorization: signatureValue
Date: date

Request Parameters

This implementation of the operation does not use request parameters.

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

Request Elements

This implementation of the operation does not use request elements.

Responses

Response Headers

This implementation of the operation can include the following response headers in addition to the response headers common to all responses. For more information, see Common Response Headers.

Name	Description
`x-amz-expiration`	If the object expiration is configured (see PUT Bucket lifecycle), the response includes this header. It includes the `expiry-date` and `rule-id` key value pairs providing object expiration information. The value of the `rule-id` is URL encoded. Type: String
`x-amz-meta-`*	If you supplied user metadata in a `PUT` object operation, 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. For example, for family, the response header would be x-amz-meta-family. Amazon S3 returns this metadata verbatim; Amazon S3 does not interpret it. Type: String
`x-amz-missing-meta`	This header is set to the number of metadata entries that were 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, with SOAP, you can create metadata with values that are not valid HTTP headers. Type: String
`x-amz-restore`	If the object is an archived object (an object whose storage class is Glacier), the response includes this header if either the archive restoration is in progress (see POST Object restore) or an archive copy is already restored. If an archive copy is already restored, the header value indicates when Amazon S3 is scheduled to delete the object copy. For exmaple, `x-amz-restore: ongoing-request="false", expiry-date="Fri, 23 Dec 2012 00:00:00 GMT"` If the object restoration is in progress, the header will return value `ongoing-request="true"`. For more information about archiving objects, go to Object Lifecycle Management in Amazon Simple Storage Service Developer Guide Type: String Default: None
`x-amz-server-side-encryption`	If the object is stored by using server-side encryption, the response includes this header with a value of the encryption algorithm that was used. Type: String Valid Values: `AES256`
`x-amz-version-id`	The version ID of the object returned. Type: String

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 metadata of an object.

HEAD /my-image.jpg HTTP/1.1
Host: bucket.s3.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: AWS AKIAIOSFODNN7EXAMPLE:02236Q3V0RonhpaBX5sCYVf1bNRuU=

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: ef8yU9AS1ed4OpIszj7UDNEHGran
x-amz-request-id: 318BC8BC143432E5
x-amz-version-id: 3HL4kqtJlcpXroDTDmjVBH40Nrjfkd
Date: Wed, 28 Oct 2009 22:32:00 GMT
Last-Modified: Sun, 1 Jan 2006 12:00:00 GMT
ETag: "fba9dede5f27731c9771645a39863328"
Content-Length: 434234
Content-Type: text/plain
Connection: close
Server: AmazonS3

If the object is scheduled to expire according to lifecycle configuration set on the bucket, the response returns x-amz-expiration tag with information when Amazon S3 will delete the object. For more information, go to Object Expiration in the Amazon Simple Storage Service Developer Guide.

HTTP/1.1 200 OK
x-amz-id-2: azQRZtQJ2m1P8R+TIsG9h0VuC/DmiSJmjXUMq7snk+LKSJeurtmfzSlGhR46GzSJ
x-amz-request-id: 0EFF61CCE3F24A26
Date: Mon, 17 Dec 2012 02:26:39 GMT
Last-Modified: Mon, 17 Dec 2012 02:14:10 GMT
x-amz-expiration: expiry-date="Fri, 21 Dec 2012 00:00:00 GMT", rule-id="Rule for testfile.txt"
ETag: "54b0c58c7ce9f2a8b551351102ee0938"
Accept-Ranges: bytes
Content-Type: text/plain
Content-Length: 14
Server: AmazonS3

Sample Request Getting Metadata From a Specified Version of an Object

The following request returns the metadata of the specified version of an object.

HEAD /my-image.jpg?versionId=3HL4kqCxf3vjVBH40Nrjfkd HTTP/1.1
Host: bucket.s3.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: AWS AKIAIOSFODNN7EXAMPLE:02236Q3V0WpaBX5sCYVf1bNRuU=

Sample Response to a Versioned HEAD Request

HTTP/1.1 200 OK
x-amz-id-2: eftixk72aD6Ap51TnqcoF8epIszj7UDNEHGran
x-amz-request-id: 318BC8BC143432E5
x-amz-version-id: 3HL4kqtJlcpXrof3vjVBH40Nrjfkd
Date: Wed, 28 Oct 2009 22:32:00 GMT
Last-Modified: Sun, 1 Jan 2006 12:00:00 GMT
ETag: "fba9dede5f27731c9771645a39863328"
Content-Length: 434234
Content-Type: text/plain
Connection: close
Server: AmazonS3

Sample Request for a Glacier Object

If you request metadata for an object that is archived in Amazon Glacier you must first restore a copy of the object. The HEAD request return the x-amz-restore header providing the status of the restoration.

HEAD /my-image.jpg HTTP/1.1
Host: bucket.s3.amazonaws.com
Date: 13 Nov 2012 00:28:38 GMT
Authorization: AWS AKIAIOSFODNN7EXAMPLE:02236Q3V0RonhpaBX5sCYVf1bNRuU=

Sample Response-Glacier Object

If the object is already restored, the x-amz-restore header provides the date when the restored copy will expire as shown in the following response.

HTTP/1.1 200 OK
x-amz-id-2: FSVaTMjrmBp3Izs1NnwBZeu7M19iI8UbxMbi0A8AirHANJBo+hEftBuiESACOMJp
x-amz-request-id: E5CEFCB143EB505A
Date: Tue, 13 Nov 2012 00:28:38 GMT
Last-Modified: Mon, 15 Oct 2012 21:58:07 GMT
x-amz-restore: ongoing-request="false", expiry-date="Wed, 07 Nov 2012 00:00:00 GMT"
ETag: "1accb31fcf202eba0c0f41fa2f09b4d7"
Accept-Ranges: bytes
Content-Type: binary/octet-stream
Content-Length: 300
Server: AmazonS3

If the restoration is in progress, then the x-amz-restore header return message accordingly.

HTTP/1.1 200 OK
x-amz-id-2: b+V2mDiMHTdy1myoUBpctvmJl95H9U/OSUm/jRtHxjh0+pCk5SvByL4xu2TDv4GM
x-amz-request-id: E2E7B6AEE4E9BD2B
Date: Tue, 13 Nov 2012 00:43:32 GMT
Last-Modified: Sat, 20 Oct 2012 21:28:27 GMT
x-amz-restore: ongoing-request="true"
ETag: "1accb31fcf202eba0c0f41fa2f09b4d7"
Accept-Ranges: bytes
Content-Type: binary/octet-stream
Content-Length: 300
Server: AmazonS3

Related Resources

GET Object

Document Conventions	« Previous Next »
Terms of Use	Did this page help you? Yes \| No \| Tell us about it...