Get bucket metadata

Stay organized with collections Save and categorize content based on your preferences.

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.

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.

?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.

?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.

?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.

?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.

?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.

?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.

?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.

?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.

?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.

?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.

?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.

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>