This page describes how to determine the storage layout of your bucket. Storage
layout refers to how objects are organized within a bucket, either in a flat
namespace or a [hierarchical namespace](https://docs.cloud.google.com/storage/docs/hns-overview). The layout is important for
applications that interact with the bucket, as object access and manipulation
methods vary depending on the layout. Storage layout also includes information
about the bucket's location.

By using the [`getStorageLayout`](https://docs.cloud.google.com/storage/docs/json_api/v1/buckets/getStorageLayout) API, your application can adapt its
behavior based on whether a bucket uses hierarchical namespace or not, ensuring
optimal compatibility and leveraging the appropriate features based on the
bucket configuration.

#### Roles required

In order to get the required permissions for getting the storage layout of a Cloud Storage bucket , ask your administrator to grant you the Storage Object User (`roles/storage.objectUser`) role on the bucket.

The role contains the `storage.objects.list` permission, which is
required to get the storage layout of the bucket.

You might also be able to get this permission with other [custom roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles) or
[predefined roles](https://docs.cloud.google.com/iam/docs/roles-permissions). To see which roles are associated with which permissions, refer to [IAM roles for Cloud Storage.](https://docs.cloud.google.com/storage/docs/access-control/iam-roles)

For instructions on granting roles on buckets, see [Use IAM with buckets.](https://docs.cloud.google.com/storage/docs/access-control/using-iam-permissions)

## Get a bucket's storage layout

### Command line

Use the [`gcloud storage buckets describe`](https://docs.cloud.google.com/sdk/gcloud/reference/storage/buckets/describe) command with the `--format` flag:

```
gcloud storage buckets describe gs://BUCKET_NAME --raw --format="default(hierarchicalNamespace)"
```

Where:

- `BUCKET_NAME` is the name of the relevant bucket. For example, `my-bucket`.

If successful and hierarchical namespace is enabled, the response looks
similar to the following example:

```
  hierarchicalNamespace:
    enabled: true
```

### JSON API

1. Have gcloud CLI [installed and initialized](https://docs.cloud.google.com/sdk/docs/install), which lets
   you generate an access token for the `Authorization` header.

2. Use [`cURL`](http://curl.haxx.se/) to call the [JSON API](https://docs.cloud.google.com/storage/docs/json_api)
   with a [`getStorageLayout`](https://docs.cloud.google.com/storage/docs/json_api/v1/buckets/getStorageLayout) request:

   ```
   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/storageLayout"
   ```

   Where `BUCKET_NAME` is the name of the
   relevant bucket. For example, `my-bucket`.

   If successful, the response looks like the following example:

   <br />

   ```json
     {
         "kind": "storage#storageLayout",
         "bucket": "my-bucket",
         "location": "us-central1",
         "locationType": "region",
         "hierarchicalNamespace":{enabled: true},
     }
   ```

   <br />

## What's next

- [Understand folders](https://docs.cloud.google.com/storage/docs/folders-overview).
- [Create and manage folders](https://docs.cloud.google.com/storage/docs/create-folders).
- [Rename folders](https://docs.cloud.google.com/storage/docs/rename-hns-folders).