HEAD Object
Description
The HEAD
operation retrieves metadata from an object without returning
the object itself. This operation is useful if you're only interested in an object's
metadata. To use HEAD
, you must have READ
access to the
object. If READ
access is granted to the anonymous user, you can request
the object's metadata without an authorization header.
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
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 ( Type: String Default: None Constraints: None | No |
If-None-Match
|
Return the object only if its entity tag ( 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-meta-*
|
If you supplied user metadata when you 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 |
|
x-amz-version-id
|
This is set to the version ID of the object returned. Type: String |
Response Elements
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
This 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 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
Sample Request Getting Metadata From a Specified Version of an Object
This operation 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 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