Get bucket metadata

To get a bucket's metadata, you make a GET request that is scoped to a bucket, and you use the appropriate query string parameter. The requested metadata is returned in an XML document in the response body. When using the XML API, each request can only return one part of a bucket's metadata.

You must have READ permission to send requests that get bucket metadata. Also, you must be authenticated to use the GET Bucket method.

Query string parameters

Exactly one of the following query parameters should be included as part of the request to get the bucket's metadata.

Parameter Description Required
billing Return the status of the Requester Pays feature for a bucket. No
cors Return the CORS configuration for a bucket. No
customPlacementConfig Applicable to buckets located in configurable dual-regions. Return the regions that constitute the configurable dual-region that a bucket is located within. No
encryptionConfig Return the default customer-managed encryption key for a bucket. No
lifecycle Return the lifecycle configuration for a bucket. No
location Return the location of the bucket. Returned values can include a region, predefined dual-region, or multi-region name. For a list of possible locations, see bucket locations. No
logging Return the logging configuration for a bucket. No
object-lock Return the object retention configuration of a bucket. If object retention is not enabled for the requested bucket, the request fails with a 404 response. No
storageClass Return the default storage class for a bucket. No
tagging Return the labels for a bucket. No
versioning Return the status of Object Versioning for a bucket. No
websiteConfig Return the website configuration for a bucket. No

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

Request headers

See common request headers.

Request body elements

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

Request syntax

The following syntax applies to GET Bucket requests that return the metadata for a bucket.

GET /?METADATA_QUERY_PARAMETER HTTP/1.1
Host: BUCKET_NAME.storage.googleapis.com
Date: DATE_AND_TIME_OF_REQUEST
Content-Length: 0
Authorization: AUTHENTICATION_STRING

Response headers

The request can return a variety of response headers depending on the request headers you use.

Response body elements

The contents of the response body depends on the query parameter you use in the request.

?billing

The following response body elements are applicable only if you use the billing query string parameter to get the status of Requester Pays for an existing bucket.

Element Description
BillingConfiguration The container for RequesterPays.
RequesterPays The status of the Requester Pays feature. The status is given as Enabled or Disabled.

?cors

The following response body elements are applicable only if you use the cors query string parameter to get the CORS configuration for an existing bucket.

Element Description
CorsConfig Container for one or more Cors configuration containers. The configurations are evaluated in the order listed within the CorsConfig container, with the first Cors container that has a configuration matching the Origin and Method of a request used to determine any CORS response headers to add to the response.
Cors Container for a CORS configuration that is applied to the bucket. There might be multiple Origins and multiple Methods in each Cors container.
Origins Container for one or more Origin elements, specifying the origins permitted for cross origin resource sharing with this Cloud Storage bucket.
Origin An Origin permitted for cross origin resource sharing with this Cloud Storage bucket. An origin that consists of only the wildcard (<Origin>*</Origin>) gives access to ALL origins.
Methods Container for one or more Method elements, specifying the HTTP methods permitted in cross origin resource sharing with this Cloud Storage bucket.
Method An HTTP method used in this configuration.
ResponseHeaders Optional container for one or more ResponseHeader elements.
ResponseHeader Specifies a response header that the user agent is permitted to share across origins.
MaxAgeSec This value is used to respond to preflight requests, indicating the number of seconds that the client (browser) is allowed to make requests before the client must repeat the preflight request. (Indicates cache expiry time.) Preflight requests are required if the request method contains non-simple headers or if the request method is not POST, GET, or HEAD. The value is returned in the Access-Control-Max-Age header in responses to preflight requests.

?customPlacementConfig

The following response body elements are applicable only if you use the customPlacementConfig query string parameter to return the regions that constitute the configurable dual-region that a bucket is located within.

If the request applies to a bucket located in a region, multi-region, or predefined dual-region, the response contains an empty DataLocations element.

Element Description
CustomPlacementConfig The container for DataLocations
DataLocations The container for a list of regions that constitute the configurable dual-region.
DataLocation One of the regions that constitute the configurable dual-region.

?encryptionConfig

The following response body elements are applicable only if you use the encryptionConfig query string parameter to get the default customer-managed encryption key used for an existing bucket.

Element Description
EncryptionConfiguration The container for DefaultKmsKeyName. If this element is empty, the bucket does not have a default key set for it.
DefaultKmsKeyName The name of the Cloud Key Management Service key resource used by default for objects added to the bucket.

?lifecycle

The following response body elements are applicable only if you use the lifecycle query string parameter to get the lifecycle configuration for an existing bucket.

Element Description
LifecycleConfiguration Container for one or more Rule elements, which define the object lifecycle management configuration for the bucket. If this element is empty, the bucket does not have an object lifecycle management configuration set for it.
Rule Defines a lifecycle management rule, which is made of an action and the conditions that must be met for the action to occur.
Action Defines the action to occur. Every Rule has exactly one and action element.
AbortIncompleteMultipartUpload Action element to abort incomplete multipart uploads and delete the parts associated with them.
Delete Action element to delete objects in the bucket.
SetStorageClass Action element to change the storage class of objects in the bucket.
Condition Conditions that must be met for the action to occur. Every Rule contains at least one condition element.
Age Condition element that matches objects over the specified age (in days).
CreatedBefore Condition element that matches objects created before midnight of the specified date in UTC. The value is an ISO date string without a timezone, for example 2019-01-15.
CustomTimeBefore Condition element that matches objects whose Custom-Time metadata contains a date that's older than the date set by this condition. CustomTimeBefore is an ISO date string without a time zone, for example 2020-02-25.
DaysSinceCustomTime Condition element that matches objects whose Custom-Time metadata is more than DaysSinceCustomTime days old.
DaysSinceNoncurrentTime Condition element relevant only for versioned objects. Matches objects that have been noncurrent for more than the specified number of days.
IsLive Condition element typically only used in conjunction with object versioning. When set to false, this condition is satisfied for any noncurrent version of an object. When set to true, this condition is satisfied for the live version of an object. If you don't use object versioning, all your objects are considered live and match when IsLive is true.
MatchesPrefix Condition element that matches objects whose names begin with the specified prefix.
MatchesStorageClass Condition element that matches objects of the specified storage class.
MatchesSuffix Condition element that matches objects whose names end with the specified suffix.
NoncurrentTimeBefore Condition element relevant only for versioned objects. Matches objects that became noncurrent on a date prior to the date specified in this condition. NoncurrentTimeBefore is an ISO date string without a time zone, for example 2020-02-25.
NumberOfNewerVersions Condition element relevant only for versioned objects. If the value is N, the condition is satisfied when there are at least N versions (including the live version) newer than this version of the object.

?location

The following response body element is applicable only if you use the location query string parameter to get the location for an existing bucket. Note that for configurable dual-regions, additional location information can be obtained by making a request for the bucket's custom placement configuration, using the customPlacementConfig query string.

Element Description
LocationConstraint The location of the bucket. Can be the name of a single region, predefined dual-region, or multi-region. For a list of locations, see bucket locations.

?logging

The following response body elements are applicable only if you use the logging query string parameter to get the logging configuration for an existing bucket.

Element Description
Logging Container for a logging configuration. If the element is empty, logging is disabled for the bucket.
LogBucket The bucket that will receive log objects.
LogObjectPrefix The object prefix for log objects.

?object-lock

The following response body elements are applicable only if you use the object-lock query string parameter to display bucket's object retention configuration.

Element Description
ObjectLockConfiguration Container for the object retention configuration.
ObjectLockEnabled Status of object retention for this bucket. Enabled is the only valid value for this element. If object retention is not enabled for the bucket, the overall request fails with a 404 response.

?storageClass

The following response body element is applicable only if you use the storageClass query string parameter to get the storage class for an existing bucket.

Element Description
StorageClass The default storage class for the bucket.

?tagging

The following response body elements are applicable only if you use the tagging query string parameter to get the labels for an existing bucket.

Element Description
Tagging The container for TagSet.
TagSet The container for all labels that are applied to the bucket.
Tag A container for an individual label. A label is composed of a key:value pair.
Key The key for a label.
Value The value for a label.

?versioning

The following response body elements are applicable only if you use the versioning query string parameter to get the status of Object Versioning for an existing bucket.

Element Description
VersioningConfiguration Container for versioning configuration. This element can be empty if Object Versioning is not enabled for the bucket.
Status Status of versioning for this bucket. Can be either Enabled or Suspended.

?websiteConfig

The following response body elements are applicable only if you use the websiteConfig query string parameter to get the website configuration for an existing bucket.

Element Description
WebsiteConfiguration Container for website configuration. If the element is empty, there is no website configuration for the bucket.
MainPageSuffix The object name suffix used to simulate directory index behavior.
NotFoundPage Name of the object to return with 404 responses.

Example

The following example retrieves the labels for a bucket named my-bucket. In this example, the bucket has two labels applied to it.

Request

GET /?tagging HTTP/1.1
Host: my-bucket.storage.googleapis.com
Date: Thu, 24 Jan 2016 02:34:56 GMT
Content-Length: 0
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg

Response

HTTP/1.1 200 OK
Date: Thu, 16 Nov 2023 02:34:56 GMT
Expires: Mon, 01 Jan 1990 00:00:00 GMT
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 196
Content-Type: text/html

<?xml version="1.0" encoding="UTF-8"?>
<Tagging>
  <TagSet>
     <Tag>
       <Key>environment</Key>
       <Value>production</Value>
     </Tag>
     <Tag>
       <Key>billing</Key>
       <Value>marketing-department</Value>
     </Tag>
  </TagSet>
</Tagging>