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 incremental data copy 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 and the incremental data copy 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
The list of configurable dual-region locations where you want to relocate the bucket.
Writable
validateOnly
boolean
When set to true, the 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.
For information about status and error codes returned by this API, see the
reference page.
Try it!
Use the APIs Explorer below to call this method on live data and see the response.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-28 UTC."],[],[],null,["# Buckets: relocate\n\nInitiates the [dry run](/storage/docs/bucket-relocation/relocate-buckets#dry-run) or the [incremental data copy](/storage/docs/bucket-relocation/relocate-buckets#incremental-data-copy) step of a [bucket relocation operation](/storage/docs/bucket-relocation/overview).\n\nUsers can use\n[Operations: get](/storage/docs/json_api/v1/operations/get) to check the status of the operation.\n\nRequired permissions\n--------------------\n\nYou must have the `storage.buckets.relocate` IAM permission on the bucket to initiate the dry run or the incremental data copy step.\n\nYou might also need the following permissions on the bucket:\n\n- `storage.bucketOperations.get` \n You need this permission to view the status of the bucket relocation operation.\n- `storage.bucketOperations.list` \n You need this permission to view the list of bucket relocation operations.\n- `storage.bucketOperations.cancel` \n You need this permission to cancel the bucket relocation operation.\n- `storage.bucket.get` \n You need this permission to view the metadata of a bucket during the [dry run](/storage/docs/bucket-relocation/relocate-buckets#dry-run) and the [incremental data copy](/storage/docs/bucket-relocation/relocate-buckets#incremental-data-copy) of the bucket relocation operation.\n- `storage.objects.list` and `storage.objects.get` \n You need these permissions to view the list of objects in a bucket that you want to relocate to another location.\n\nRequest\n-------\n\n### HTTP request\n\n```\nPOST https://storage.googleapis.com/storage/v1/b/bucket/relocate\n```\n\nIn addition to [standard query parameters](/storage/docs/json_api/v1/parameters#query),\nthe following query parameters apply to this method.\n\nTo see an example of how to include query parameters in a request, see the\n[JSON API Overview](/storage/docs/json_api#query_parameters) page.\n\n### Parameters\n\n### Request body\n\nIn the request body, supply the following properties:\n\nResponse\n--------\n\nInitiating a bucket relocation process starts a long-running operation.\nYou'll receive an operation ID and a description of the operation. To track the completion of\nthe bucket relocation operation, you'll need to track its progress.\nFor information about how to track the progress\nof the bucket relocation operation, see [Get details of a long-running operation](/storage/docs/json_api/v1/operations/get).\n\nFor information about status and error codes returned by this API, see the\n[reference page](/storage/docs/json_api/v1/status-codes).\n\nTry it!\n-------\n\n\nUse the APIs Explorer below to call this method on live data and see the response."]]
