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>