Objects: move
Moves an object within a bucket.
This operation moves a source object to a destination object in the same bucket by renaming the object. Themove itself is an atomic transaction, ensuring all steps eithercomplete successfully or no changes are made.
The move operation performs the following actions:
- The source object is deleted as follows:
- No early deletion fee is incurred.
- Soft delete retention period is not applied.
- Audit logs andnotification messages are generated for the object.
- The destination object is created with the same data and metadata as the source object except for the following changes:
- A new object
name - A new
generation number - A new
metageneration number, set to1 - New
createandupdatetimestamps - The destination object is moved to Standard storage if the bucket has Autoclass enabled
- A new object
- If a destination folder doesn't exist, the move operation creates the folder along with the destination object. The move operation also automatically creates any necessary parent folders.
Consider the following points when using themove method:
- The source and destination must have different object names.
- The source object must exist. You can only move existing objects.
- If an object already exists at the destination, the move operation replaces the existing object. The replaced object will become noncurrent or soft-deleted depending on whether Object Versioning or soft delete is enabled. You can disable the replacement behavior using preconditions on the request.
Required permissions
The authenticated user must have the following IAM permissions to use this method:
- Permissions required on the source object:
storage.objects.deleteandstorage.objects.getorstorage.objects.move(required only to move an object without allowing read or delete access)- Permissions required on the destination object:
storage.objects.createstorage.objects.delete(required only for replacing an object)storage.folders.create(required only for automatically creating any missing parent folders)storage.objects.getIamPolicy(only required ifprojectionisfulland the relevant bucket hasuniform bucket-level access disabled)
Request
HTTP request
POST https://storage.googleapis.com/storage/v1/b/bucket/o/sourceObject/moveTo/o/destinationObject
In addition tostandard query parameters, the following query parameters apply to this method.
To see an example of how to include query parameters in a request, see theJSON API Overview page.
Parameters
| Parameter name | Value | Description |
|---|---|---|
| Path parameters | ||
bucket | string | Name of the bucket containing the object you want to move. |
sourceObject | string | Name of the source object. For information about how to URL encode object names to be path safe, seeEncoding URI path parts. |
destinationObject | string | Name of the new object. Required when the object metadata is not otherwise provided. Overrides the object metadata'sname value, if any. For information about how to URL encode object names to be path safe, seeEncoding URI path parts. |
| Optional query parameters | ||
ifGenerationMatch | long | Makes the operation conditional on there being a live destination object with a generation number that matches the given value. SettingifGenerationMatch to0 makes the operation succeed only if there is no live destination object. |
ifGenerationNotMatch | long | Makes the operation conditional on there being a live destination object with a generation number that does not match the given value. If no live destination object exists, the precondition fails. SettingifGenerationNotMatch to0 makes the operation succeed if there is a live version of the object. TheifGenerationMatch andifGenerationNotMatch parameters are mutually exclusive. Specifying both parameters in a single request results in an error. |
ifMetagenerationMatch | long | Makes the operation conditional on there being a live destination object with a metageneration number that matches the given value. |
ifMetagenerationNotMatch | long | Makes the operation conditional on there being a live destination object with a metageneration number that does not match the given value. TheifMetagenerationMatch andifMetagenerationNotMatch parameters are mutually exclusive. Specifying both parameters in a single request result in an error. |
ifSourceGenerationMatch | long | Makes the operation conditional on whether the source object's generation matches the given value. |
ifSourceGenerationNotMatch | long | Makes the operation conditional on whether the source object's generation does not match the given value. TheifSourceGenerationMatch andifSourceGenerationNotMatch parameters are mutually exclusive. Specifying both parameters in a single request result in an error. |
ifSourceMetagenerationMatch | long | Makes the operation conditional on whether the source object's current metageneration matches the given value. |
ifSourceMetagenerationNotMatch | long | Makes the operation conditional on whether the source object's current metageneration does not match the given value. TheifSourceMetagenerationMatch andifSourceMetagenerationNotMatch parameters are mutually exclusive. Specifying both parameters in a single request result in an error. |
projection | string | Set of properties to return. Defaults tonoAcl.Acceptable values are:
|
Request body
Do not supply a request body with this method.
Response
If successful, this method returns the destination object'sresource in the response body.
The following errors could occur:
- If the source object is subject to either anobject retention policy orbucket retention policy, the request fails with a
403 Forbidden errorwith the reasonretentionPolicyNotMet. - Likewise, if a live object already exists at the destination and it is subject to either anobject retention policy orbucket retention policy, the request fails with a
403 Forbiddenerror with the reasonretentionPolicyNotMet.
For information about status and error codes returned by this API, see thereference page.
Try it!
Use the APIs Explorer below to call this method on live data and see the response.
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-12-17 UTC.