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

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.

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 retrieve the metadata from 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 a HTTP status code 404 ("no such key") error.

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

Requests

Syntax

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

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' HEAD 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

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, Amazon 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, Amazon S3 returns the 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 metadata from an object stored in 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

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	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 is 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-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-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 returns the x-amz-replication-status header in the response as follows: If requesting object from the source bucket — Amazon S3 returns the x-amz-replication-status header if object in your request is eligible for replication. For example, suppose that 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 returns 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 returns the x-amz-replication-status header with value REPLICA if object in your request is a replica that Amazon S3 created. For more information, see Cross-Region Replication in the Amazon Simple Storage Service Developer Guide. Valid Values: PENDING, COMPLETED, FAILED, REPLICA 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 example, 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 returns the value ongoing-request="true". For more information about archiving objects, see Transitioning Objects: General Considerations in the Amazon Simple Storage Service Developer Guide Type: String Default: None
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 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(SSE-C) decryption was requested, the response includes this header confirming the decryption algorithm used. Type: String Valid Values: AES256
x-amz-server-side​-encryption​-customer-key-MD5	If SSE-C 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, see Storage Classes in the Amazon Simple Storage Service Developer Guide. Type: String Default: None
x-amz-version-id	The version ID of the object returned. Type: String
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

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 a lifecycle configuration set on the bucket, the response returns the x-amz-expiration tag with information about when Amazon S3 will delete the object. For more information, see Transitioning Objects: General Considerations 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 for Getting Metadata from an Object Part

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

HEAD /test.txt?partNumber=1 HTTP/1.1
Host: bucket.s3.amazonaws.com
Date: Wed, 12 Jun 2019 16:52:50 GMT
Authorization: authorization string

Sample Response to an Object Part HEAD Request

HTTP/1.1 206 Partial Content
x-amz-id-2: oMGCGCG2SFoQ//zIZ/7zCrGI1bIa+STIEhXLeFVbYnoVszvgXHepSQuJ3U/kFBNiLFhZbqlhevQ=
x-amz-request-id: 82291A7EE7DD9E30
Date: Wed, 12 Jun 2019 16:52:53 GMT
Last-Modified: Mon, 06 Mar 2017 21:21:28 GMT
ETag: "46ea6cc5c77a33c569e5700f0ca465d8-2"
x-amz-mp-parts-count: 2
x-amz-version-id: null
Accept-Ranges: bytes
Content-Range: bytes 0-7495543/14990261
Content-Type: binary/octet-stream
Content-Length: 7495544
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 an Glacier Object

For an archived object, the x-amz-restore header provides the date when the restored copy expires, as shown in the following response. Even if the object is stored in Glacier, all object metadata is still available.

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 returns a 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