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](https://docs.cloud.google.com/storage/docs/requester-pays.md.txt) feature for a bucket. | No |
| `cors` | Return the [CORS configuration](https://docs.cloud.google.com/storage/docs/cross-origin.md.txt) for a bucket. | No |
| `customPlacementConfig` | Applicable to buckets located in [configurable dual-regions](https://docs.cloud.google.com/storage/docs/locations.md.txt#location-dr). Return the regions that constitute the configurable dual-region that a bucket is located within. | No |
| `encryptionConfig` | Return the encryption settings for a bucket: - The [default customer-managed encryption key](https://docs.cloud.google.com/storage/docs/encryption/customer-managed-keys.md.txt) for a bucket - [Which encryption methods are allowed or restricted](https://docs.cloud.google.com/storage/docs/encryption/enforce-encryption-types.md.txt) for new objects in a bucket | No |
| `lifecycle` | Return the [lifecycle configuration](https://docs.cloud.google.com/storage/docs/lifecycle.md.txt) 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](https://docs.cloud.google.com/storage/docs/locations.md.txt). | No |
| `logging` | Return the [logging configuration](https://docs.cloud.google.com/storage/docs/access-logs.md.txt) for a bucket. | No |
| `object-lock` | Return the [object retention configuration](https://docs.cloud.google.com/storage/docs/object-lock.md.txt) 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](https://docs.cloud.google.com/storage/docs/storage-classes.md.txt) for a bucket. | No |
| `tagging` | Return the [labels](https://docs.cloud.google.com/storage/docs/tags-and-labels.md.txt#bucket-labels) for a bucket. | No |
| `versioning` | Return the status of [Object Versioning](https://docs.cloud.google.com/storage/docs/object-versioning.md.txt) for a bucket. | No |
| `websiteConfig` | Return the [website configuration](https://docs.cloud.google.com/storage/docs/static-website.md.txt) for a bucket. | No |

See [signed URL query string parameters](https://docs.cloud.google.com/storage/docs/authentication/canonical-requests.md.txt#required-query-parameters) for information on the parameters
you include when creating and using [signed URLs](https://docs.cloud.google.com/storage/docs/access-control/signed-urls.md.txt).

## Request headers

See [common request headers](https://docs.cloud.google.com/storage/docs/xml-api/get-bucket.md.txt#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](https://docs.cloud.google.com/storage/docs/xml-api/get-bucket-metadata.md.txt#query-parameters) 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](https://docs.cloud.google.com/storage/docs/using-requester-pays.md.txt) 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](https://docs.cloud.google.com/storage/docs/using-cors.md.txt) 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](http://www.w3.org/TR/cors/#simple-method) 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](https://docs.cloud.google.com/storage/docs/locations.md.txt#location-dr) 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](https://docs.cloud.google.com/storage/docs/locations.md.txt#location-dr). |
| `DataLocation` | One of the regions that constitute the [configurable dual-region](https://docs.cloud.google.com/storage/docs/locations.md.txt#location-dr). |

### `?encryptionConfig`

The following response body elements are applicable only if you use the
`encryptionConfig` query string parameter to get the encryption settings
for an existing bucket.

| Element | Description |
|---|---|
| `EncryptionConfiguration` | Container that defines the following encryption settings for the bucket: - The [default customer-managed encryption key](https://docs.cloud.google.com/storage/docs/encryption/using-customer-managed-keys.md.txt), represented by the `DefaultKmsKeyName` element. - [Which encryption methods are allowed or restricted](https://docs.cloud.google.com/storage/docs/encryption/enforce-encryption-types.md.txt) for new objects in the bucket, represented by the elements `CustomerManagedEncryptionEnforcement`, `CustomerSuppliedEncryptionEnforcement`, and `GoogleManagedEncryptionEnforcement`. If this element is empty, then all encryption methods are allowed, and no default Cloud Key Management Service key is set for the bucket. |
| `DefaultKmsKeyName` | The name of the Cloud KMS key resource used by default for objects added to the bucket. |
| `CustomerManagedEncryptionEnforcement` | Controls the use of [customer-managed encryption keys (CMEKs)](https://docs.cloud.google.com/storage/docs/encryption/customer-managed-keys.md.txt) to encrypt objects in this bucket. If omitted, then creating new objects with CMEKs is allowed. If set, then new objects must comply with the encryption enforcement configuration. This property applies when new objects are created, including when soft-deleted objects are restored. Changing this property has no effect on existing objects. This element is a container for `RestrictionMode` and `EffectiveTime` elements. |
| `CustomerSuppliedEncryptionEnforcement` | Controls the use of [customer-supplied encryption keys](https://docs.cloud.google.com/storage/docs/encryption/customer-supplied-keys.md.txt) to encrypt objects in this bucket. If omitted, then creating new objects with customer-supplied encryption keys is allowed. If set, then new objects must comply with the encryption enforcement configuration. This property applies when new objects are created, including when soft-deleted objects are restored. Changing this property has no effect on existing objects. This element is a container for `RestrictionMode` and `EffectiveTime` elements. |
| `GoogleManagedEncryptionEnforcement` | Controls the use of [standard encryption (Google default encryption)](https://docs.cloud.google.com/storage/docs/encryption.md.txt) to encrypt objects in this bucket. If omitted, then creating new objects with standard encryption is allowed. If set, then new objects must comply with the encryption enforcement configuration. This property applies when new objects are created, including when soft-deleted objects are restored. Changing this property has no effect on existing objects. This element is a container for `RestrictionMode` and `EffectiveTime` elements. |
| `RestrictionMode` | The enforcement configuration for an encryption method. The following values are supported: - `NotRestricted`: new objects can use the encryption type. - `FullyRestricted`: new objects can't use the encryption type. |
| `EffectiveTime` | The time when the encryption enforcement configuration for an encryption method was set to `FullyRestricted`. This element is returned only when an encryption type is restricted. If you update a bucket to allow a specific encryption type, then the `EffectiveTime` field for that encryption type is cleared. Specified in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format. |

### `?lifecycle`

The following response body elements are applicable only if you use the
`lifecycle` query string parameter to
[get the lifecycle configuration](https://docs.cloud.google.com/storage/docs/managing-lifecycles.md.txt) 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](https://docs.cloud.google.com/storage/docs/multipart-uploads.md.txt) and delete the parts associated with them. |
| `Delete` | Action element to delete objects in the bucket. |
| `SetStorageClass` | Action element to change the [storage class](https://docs.cloud.google.com/storage/docs/storage-classes.md.txt) 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](https://docs.cloud.google.com/storage/docs/metadata.md.txt#custom-time) 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](https://docs.cloud.google.com/storage/docs/metadata.md.txt#custom-time) 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](https://docs.cloud.google.com/storage/docs/object-versioning.md.txt). 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](https://docs.cloud.google.com/storage/docs/lifecycle.md.txt#matchesprefix-suffix). |
| `MatchesStorageClass` | Condition element that matches objects of the specified [storage class](https://docs.cloud.google.com/storage/docs/storage-classes.md.txt). |
| `MatchesSuffix` | Condition element that matches objects whose names end with the specified [suffix](https://docs.cloud.google.com/storage/docs/lifecycle.md.txt#matchesprefix-suffix). |
| `NoncurrentTimeBefore` | Condition element relevant only for versioned objects. Matches objects that became [noncurrent](https://docs.cloud.google.com/storage/docs/object-versioning.md.txt) 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. |
| `SizeAboveBytes` | Condition element that matches objects whose size in bytes, excluding metadata, is larger than the specified value. |
| `SizeBelowBytes` | Condition element that matches objects whose size in bytes, excluding metadata, is smaller than the specified value. |

### `?location`

The following response body element is applicable only if you use the `location`
query string parameter to [get the location](https://docs.cloud.google.com/storage/docs/getting-bucket-metadata.md.txt) 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](https://docs.cloud.google.com/storage/docs/locations.md.txt). |

### `?logging`

The following response body elements are applicable only if you use the
`logging` query string parameter to
[get the logging configuration](https://docs.cloud.google.com/storage/docs/access-logs.md.txt) 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](https://docs.cloud.google.com/storage/docs/using-object-lock.md.txt).

| 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](https://docs.cloud.google.com/storage/docs/changing-default-storage-class.md.txt) 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](https://docs.cloud.google.com/storage/docs/using-bucket-labels.md.txt) 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](https://docs.cloud.google.com/storage/docs/using-object-versioning.md.txt) 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>
```