Stay organized with collectionsSave and categorize content based on your preferences.
Retrieves object metadata. Whenalt=mediais included as a query
parameter, retrieves object data.
This method supports the use of theRangeheader, which can be used to retrieve only part of the object data.
For examples of performing object downloads with different Cloud Storage tools and client
libraries, see theDownloading Objects guide.
Required permissions
The authenticated user must have thestorage.objects.getIAM
permission to use this method. To return object ACLs, the authenticated user must also have thestorage.objects.getIamPolicypermission.
Request
HTTP request
GET https://storage.googleapis.com/storage/v1/b/bucket/o/object
To see an example of how to include query parameters in a request, see theJSON API Overviewpage.
Parameters
Parameter name
Value
Description
Path parameters
bucket
string
Name of the bucket in which the object resides.
object
string
Name of the object. For information about how to URL encode object names to be path safe,
seeEncoding URI path parts.
Optional query parameters
alt
string
Type of data to return. Defaults tojson.
Acceptable values are:
json: Return object metadata.
media: Return object data. Not supported for soft-deleted objects.
generation
long
If present, selects a specific revision of this object (as opposed to the latest version,
the default). IfsoftDeletedistrue, this parameter is
required.
ifGenerationMatch
long
Makes the operation conditional on whether the object's current generation matches the
given value. Setting to 0 makes the operation succeed only if there are no live versions
of the object.
ifGenerationNotMatch
long
Makes the operation conditional on whether the object's current generation does not match
the given value. If no live object exists, the precondition fails. Setting to 0 makes the
operation succeed only if there is a live version of the object.
ifMetagenerationMatch
long
Makes the operation conditional on whether the object's current metageneration matches
the given value.
ifMetagenerationNotMatch
long
Makes the operation conditional on whether the object's current metageneration does not
match the given value.
When getting the metadata for a soft-deleted object, therestoreTokenis
only required when thenameandgenerationvalues of the objectdo not uniquely identify
it. Otherwise, including arestoreTokenin the request is
optional.
softDeleted
boolean
Iftrue, returns the metadata of thesoft-deleted object.
Iftrue,generationmust also be specified, andalt=mediacannot be specified.
Optional extension headers
X-Goog-Encryption-Algorithm
string
The encryption algorithm to use, which must beAES256. Use this header if the
object is encrypted with acustomer-supplied
encryption keyand you want the object's data or content hashes returned in the
response.
X-Goog-Encryption-Key
string
AnRFC 4648Base64-encoded string of your AES-256 encryption key. Use this header if the object is
encrypted with acustomer-supplied
encryption keyand you want the object's data or content hashes returned in the
response.
X-Goog-Encryption-Key-Sha256
string
AnRFC 4648Base64-encoded string of the SHA256 hash of your encryption key. Use this header if the
object is encrypted with acustomer-supplied
encryption keyand you want the object's data or content hashes returned in the
response.
Request body
Do not supply a request body with this method.
Response
By default, this responds with anobject
resourcein the response body. If you provide the URL parameteralt=media,
then it will respond with the object data in the response body.
For information about status and error codes returned by this API, see thereference page.
Try it!
Use the APIs Explorer below to call this method on live data and see the response.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[],[],null,["# Objects: get\n\nRetrieves object metadata. When `alt=media` is included as a query\nparameter, retrieves object data.\n\nThis method supports the use of the [`Range`](/storage/docs/json_api/v1/parameters#range)\nheader, which can be used to retrieve only part of the object data.\n\nFor examples of performing object downloads with different Cloud Storage tools and client\nlibraries, see the [Downloading Objects guide](/storage/docs/downloading-objects).\n\nRequired permissions\n--------------------\n\nThe authenticated user must have the `storage.objects.get` IAM\npermission to use this method. To return object ACLs, the authenticated user must also have the\n`storage.objects.getIamPolicy` permission.\n\nRequest\n-------\n\n### HTTP request\n\n```\nGET https://storage.googleapis.com/storage/v1/b/bucket/o/object\n```\n\nIn addition to [standard query parameters](/storage/docs/json_api/v1/parameters#query),\nthe following query parameters apply to this method.\n\nTo see an example of how to include query parameters in a request, see the\n[JSON API Overview](/storage/docs/json_api#query_parameters) page.\n\n### Parameters\n\n### Request body\n\nDo not supply a request body with this method.\n\nResponse\n--------\n\nBy default, this responds with an [object\nresource](/storage/docs/json_api/v1/objects#resource) in the response body. If you provide the URL parameter `alt=media`,\nthen it will respond with the object data in the response body.\n\nFor information about status and error codes returned by this API, see the\n[reference page](/storage/docs/json_api/v1/status-codes).\n\nTry it!\n-------\n\nUse the APIs Explorer below to call this method on live data and see the response."]]
