Initiates the [dry run](https://docs.cloud.google.com/storage/docs/bucket-relocation/relocate-buckets.md.txt#dry-run) or the [relocation](https://docs.cloud.google.com/storage/docs/bucket-relocation/relocate-buckets.md.txt#initiate-relocation) step of a [bucket relocation operation](https://docs.cloud.google.com/storage/docs/bucket-relocation/overview.md.txt).

Users can use
`Operations: get` to check the status of the operation.

## Required permissions

You must have the `storage.buckets.relocate` IAM permission on the bucket to initiate the dry run or the bucket relocation step.

You might also need the following permissions on the bucket:

- `storage.bucketOperations.get`   
  You need this permission to view the status of the bucket relocation operation.
- `storage.bucketOperations.list`   
  You need this permission to view the list of bucket relocation operations.
- `storage.bucketOperations.cancel`   
  You need this permission to cancel the bucket relocation operation.
- `storage.bucket.get`  
  You need this permission to view the metadata of a bucket during the [dry run](https://docs.cloud.google.com/storage/docs/bucket-relocation/relocate-buckets.md.txt#dry-run) and the [relocation](https://docs.cloud.google.com/storage/docs/bucket-relocation/relocate-buckets.md.txt#initiate-relocation) step of the bucket relocation operation.
- `storage.objects.list` and `storage.objects.get`  
  You need these permissions to view the list of objects in a bucket that you want to relocate to another location.

## Request

### HTTP request

```
POST https://storage.googleapis.com/storage/v1/b/bucket/relocate
```

In addition to [standard query parameters](https://docs.cloud.google.com/storage/docs/json_api/v1/parameters.md.txt#query),
the following query parameters apply to this method.

To see an example of how to include query parameters in a request, see the
[JSON API Overview](https://docs.cloud.google.com/storage/docs/json_api.md.txt#query_parameters) page.

### Parameters

| Parameter name | Value | Description |
|---|---|---|
| **Path parameters** |||
| `bucket` | `string` | Name of the bucket that you want to relocate. |

### Request body

In the request body, supply the following properties:

| Property name | Value | Description | Notes |
|---|---|---|---|
| **Required parameters** ||||
| `destinationLocation` | `string` | The [destination location](https://docs.cloud.google.com/storage/docs/locations.md.txt#available-locations) of the bucket. | Writable |
| **Optional parameters** ||||
| `destinationCustomPlacementConfig` | `object` | The bucket's destination placement configuration if relocating to a [configurable dual-region](https://docs.cloud.google.com/storage/docs/locations.md.txt#configurable). | Writable |
| `destinationCustomPlacementConfig.dataLocations` | `list of strings` | The list of configurable dual-region locations where you want to relocate the bucket. | Writable |
| `validateOnly` | `boolean` | When set to `true`, the [dry run](https://docs.cloud.google.com/storage/docs/bucket-relocation/relocate-buckets.md.txt#dry-run) of the bucket relocation operation starts. | Writable |

## Response

Initiating a bucket relocation process starts a long-running operation.
You'll receive an operation ID and a description of the operation. To track the completion of
the bucket relocation operation, you'll need to track its progress.
For information about how to track the progress
of the bucket relocation operation, see [Get details of a long-running operation](https://docs.cloud.google.com/storage/docs/json_api/v1/operations/get.md.txt).

For information about status and error codes returned by this API, see the
[reference page](https://docs.cloud.google.com/storage/docs/json_api/v1/status-codes.md.txt).

## Try it!


Use the APIs Explorer below to call this method on live data and see the response.