HEAD Object

Lists metadata for an object.

If the object does not exist, Cloud Storage returns a 404 Not Found status code.

Query string parameters

Parameter Description Required
generation You can use this if you want to fetch a specific object generation. No

See signed URL query string parameters for information on the parameters you include when creating and using signed URLs.

Request headers

Header Description Required
Authorization The authentication string for the request. Yes
Content-Length

The length of the request body without headers (in bytes).

No
Date The date and time of the request. No
Host The URI for Cloud Storage. For more information, see Request Endpoints. Yes
If-Match An entity tag (ETag). If the ETag you specify is the same as the ETag for the object, then the metadata is returned. No
If-Modified-Since A date and time. If the object has been modified later than the date and time you specify, then the metadata is returned. No
If-None-Match An entity tag (ETag). If the ETag you specify is different from the ETag for the object, then the metadata is returned. No
If-Unmodified-Since A date and time. If the object has not been modified later than the date you specify, then the metadata is returned. No
Range The range (in bytes) that you want returned. No
x-goog-if-generation-match If the generation you specify is the same as the generation for the object, then the metadata is returned. No
x-goog-if-metageneration-match If the metageneration you specify is the same as the metageneration for the object, then the metadata is returned. No
x-goog-user-project The project to be billed for charges associated with the request. No

Request body elements

This request does not include an XML document in the request body.

Request syntax

HEAD /OBJECT_NAME HTTP/1.1
Host: BUCKET_NAME.storage.googleapis.com
Date: DATE
Content-Length: 0
Authorization: AUTHENTICATION_STRING
Range: bytes=BYTE_RANGE
If-Match: ENTITY_TAG
If-Modified-Since: DATE
If-None-Match: ENTITY_TAG
If-Unmodified-Since: DATE

Response headers

The request can return a variety of response headers depending on the request headers you use, including: Cache-Control, Content-Length, Content-Type, Content-Disposition, ETag, and Last-Modified.

Response body elements

The response does not include an XML document in the response body. Error responses to HEAD requests also do not contain a response body.

Example

The following sample gets metadata for an object named paris.jpg that's in a bucket named travel-maps.

Request

HEAD /paris.jpg HTTP/1.1
Host: travel-maps.storage.googleapis.com
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg

Response

...
expires: Wed, 30 May 2018 21:41:23 GMT
date: Wed, 30 May 2018 21:41:23 GMT
cache-control: private, max-age=0
last-modified: Wed, 30 May 2018 20:36:34 GMT
etag: "2218880ef78838266ecd7d4c1b742a0e"
x-goog-generation: 1486161811706000
x-goog-metageneration: 15
x-goog-stored-content-encoding: identity
x-goog-stored-content-length: 328
content-type: image/jpg
x-goog-hash: crc32c=HBrbzQ==
x-goog-hash: md5=OCydg52+pPG1Bwawjsl7DA==
x-goog-storage-class: STANDARD
accept-ranges: bytes
content-length: 328
...