Download an object
Downloads an object.
GET requests for objects can include a Range header as defined in the HTTP1.1 RFC to limit the scope of the returned data within the object, but beaware that incertain circumstances therange header is ignored.
Objects that are stored in Cloud Storage in a compressed state can beautomatically decompressed as part of adownload request when certain criteria are met. Thistranscoding behavioreliminates the need for a requester to decompress the object.
Requests can also include If-Modified-Since or If-Unmodified-Since headers, causing theresponse to omit the body if the object has not been modified, or has beenmodified, since a specified timestamp. If the object does not meet an If-Modified-Since header condition, the response is a 304 Not Modified, and if theobject fails to meet an If-Unmodified-Since header condition, the response is412 Precondition Failed.
Similarly, requests can include If-Match and If-None-Match headers with an ETag to match. If the object does not match an If-Matchheader condition, the response is 412 Precondition Failed, and if the objectmatches the given hash in an If-None-Match header, the response is 304 NotModified.
See theDownloading Objects guide forinstructions on how to download an object.
Query string parameters
| Parameter | Description | Required |
|---|---|---|
generation | You can use this if you want to fetch a specific object version. | No |
Seesigned URL query string parameters for information on the parametersyou include when creating and usingsigned URLs.
Request headers
In addition tocommon request headers, thefollowing can be used.
| Header | Description | Required |
|---|---|---|
If-Match | An entity tag (ETag). If the ETag you specify is the same as the ETag for the object, then the object is downloaded. | No |
If-Modified-Since | A date and time. If the object has been modified later than the date and time you specify, then the object is downloaded. | No |
If-None-Match | An entity tag (ETag). If the ETag you specify is different from the ETag for the object, then the object is downloaded. | No |
If-Unmodified-Since | A date and time. If the object has not been modified later than the date you specify, then the object is downloaded. | No |
Range | An object's range (in bytes) that you want to download. Warning: The checksum(s) returned when downloading data from Cloud Storage cover the complete object content. Thus, if you specify a request range there's no way to detect data corruption for that byte range alone. We therefore recommend using range requests only for restarting the download of a full object after the last received offset, because in that case you can compute and validate the checksum when the full download completes. | No |
x-goog-if-generation-match | In order for the request to succeed, the value you specify for this header must match thegeneration of the object you're requesting. If it does not, the request fails with a412 Precondition Failed status code. Also see thegeneration query parameter. | No |
x-goog-if-metageneration-match | In order for the request to succeed, the value you specify for this header must match themetageneration of the object you're requesting. If it does not, the request fails with a412 Precondition Failed status code. | No |
To download an object encrypted by a customer-supplied encryption key, use theheaders listed on the Encryption page in your request.
Request body elements
This request does not include an XML document in the request body.
Request syntax
The following syntax applies to GET Object requests that don't use theacl query string parameter.
GET /OBJECT_NAME HTTP/1.1Host:BUCKET_NAME.storage.googleapis.comContent-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 contains the object data.
Example
The following example downloads an object named paris.jpg that's in a bucketnamed travel-maps.
Request
GET /paris.jpg HTTP/1.1Host: travel-maps.storage.googleapis.comContent-Length: 0Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg
Response
HTTP/1.1 200 OKContent-Type: image/jpgLast-Modified: Fri, 19 Feb 2010 22:13:49 GMTETag: "2281880ef78388266ecd7d4c1b472a0e"Content-Length: 328Date: Fri, 19 Feb 2010 22:13:49 GMT328 bytes of data...
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.