HEAD Object
Lists metadata for an object.
If the object does not exist, Cloud Storage returns a404 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 |
Seesigned URL query string parameters for information on the parametersyou include when creating and usingsigned 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, seeRequest 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 | Including this header causes the response to contain aContent-Range header. However, since HEAD Object requests don't contain a response body, theRange header doesn't otherwise have an effect on the request. | 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.1Host:BUCKET_NAME.storage.googleapis.comDate:DATEContent-Length: 0Authorization:AUTHENTICATION_STRINGRange: bytes=BYTE_RANGEIf-Match:ENTITY_TAGIf-Modified-Since:DATEIf-None-Match:ENTITY_TAGIf-Unmodified-Since:DATE
Response headers
The request can return a variety of response headers depending on the requestheaders you use, including:Cache-Control,Content-Length,Content-Type,Content-Disposition,ETag, andLast-Modified.
Response body elements
The response does not include an XML document in the response body. Errorresponses to HEAD requests also do not contain a response body.
Example
The following sample gets metadata for an object namedparis.jpg that's in abucket namedtravel-maps.
Request
HEAD /paris.jpg HTTP/1.1Host: travel-maps.storage.googleapis.comAuthorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg
Response
...expires: Wed, 30 May 2018 21:41:23 GMTdate: Wed, 30 May 2018 21:41:23 GMTcache-control: private, max-age=0last-modified: Wed, 30 May 2018 20:36:34 GMTetag: "2218880ef78838266ecd7d4c1b742a0e"x-goog-generation: 1486161811706000x-goog-metageneration: 15x-goog-stored-content-encoding: identityx-goog-stored-content-length: 328content-type: image/jpgx-goog-hash: crc32c=HBrbzQ==x-goog-hash: md5=OCydg52+pPG1Bwawjsl7DA==x-goog-storage-class: STANDARDaccept-ranges: bytescontent-length: 328...
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-02-19 UTC.