Use soft-deleted objects

This page describes how to list, access, and restore soft-deleted objects.

Before you begin

To get the permissions that you need to list, access, and restore soft-deleted objects, ask your administrator to grant you the Storage Admin ( roles/storage.admin ) IAM role on the bucket, managed folder, or project.

This predefined role contains the permissions required to list, access, and restore soft-deleted objects. To see the exact permissions that are required, expand the Required permissionssection:

Required permissions

The following permissions are required to list, access, and restore soft-deleted objects:

storage.buckets.get (this permission is only required for using the Google Cloud console to perform the instructions on this page)
storage.buckets.list (this permission is only required for using the Google Cloud console to perform the instructions on this page)
storage.objects.get (this permission is only required for using the Google Cloud console to perform the instructions on this page)
storage.objects.list
storage.objects.restore
storage.objects.create
storage.objects.delete (this permission is only required for restoring objects in a way that causes existing objects to be overwritten)
storage.buckets.restore (this permission is only required for bulk restoring soft-deleted objects)

For information about granting roles on buckets, see Use IAM with buckets . For information about granting roles on projects, see Manage access to projects .

In order to manage long-running operations that get initiated from soft delete methods, you might need additional roles and permissions. See required roles for long-running operations to learn more.

List all of the soft-deleted objects in a bucket

Use the following instructions to list all of the soft-deleted objects in a bucket:

Console

In the Google Cloud console, go to the Cloud Storage Buckets page.

Go to Buckets
In the list of buckets, click the name of the bucket you want to view the soft-deleted objects of. The Bucket detailspage opens with the Objectstab selected.
In the Showlist, select Soft-deleted objects only. A list of soft-deleted objects is displayed.

Command line

To display a list of all the soft-deleted objects in a bucket, use the gcloud storage ls command with the --soft-deleted flag and the ** wildcard . Note that you might need to surround the wildcard expression with quotes.

gcloud storage ls gs:// BUCKET_NAME 
/** --soft-deleted

Replace the following:

BUCKET_NAME : the name of the bucket. For example, my-bucket .

REST APIs

JSON API

Have gcloud CLI installed and initialized , which lets you generate an access token for the Authorization header.

Use cURL to call the JSON API with a request to list objects that uses the ?softDeleted query parameter:

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/ BUCKET_NAME 
/o?softDeleted=true"

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

View all of the soft-deleted versions of an object

Use the following instructions to view all the soft-deleted versions of a specific object in your bucket:

Console

In the Google Cloud console, go to the Cloud Storage Buckets page.

Go to Buckets
In the list of buckets, click the name of the bucket that contains the object you want to view soft-deleted versions of. The Bucket detailspage opens with the Objectstab selected.
Click the object that you want to view all the soft-deleted versions of. The Object detailspage displays.
Click the Version Historytab.
In the Showlist, select Soft-deleted objects only. A list of all the soft-deleted versions for that object displays.

Command line

To display a list of all the soft-deleted versions of an object in a bucket, use the gcloud storage ls command:

gcloud storage ls gs:// BUCKET_NAME 
/ OBJECT_NAME 
--soft-deleted

Replace the following:

BUCKET_NAME : the name of the bucket. For example, my-bucket .
OBJECT_NAME : the name of the object you want to view all the versions of.

REST APIs

JSON API

Have gcloud CLI installed and initialized , which lets you generate an access token for the Authorization header.
Use cURL to call the JSON API with a request to list objects that uses the ?softDeleted query parameter:
```
curl -X GET \
  -H "Authorization: Bearer OAUTH2_TOKEN 
" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/ BUCKET_NAME 
/o?matchGlob= OBJECT_NAME 
&softDeleted=true"
```
Replace the following:
- BUCKET_NAME : the name of the bucket. For example, my-bucket .
- OBJECT_NAME : the name of the object for which you want to view all versions.

Restore a soft-deleted object

You can restore a specific version of a soft-deleted object in your bucket. Note that you cannot restore objects in a soft-deleted bucket. To restore objects in a soft-deleted bucket, you must first restore the soft-deleted bucket .

Use the following instructions to restore a soft-deleted object:

Console

In the Google Cloud console, go to the Cloud Storage Buckets page.

Go to Buckets
In the list of buckets, click the name of the bucket that contains the soft-deleted objects that you want to restore. The Bucket detailspage opens with the Objectstab selected.
In the Showlist, select Soft-deleted objects only.
Navigate to the object, which may be located in a folder.
Click the soft-deleted object. The Object detailspage displays.
In the Showlist, select Soft-deleted objects only. A list of all the soft-deleted versions of that object displays.
To restore a specific soft-deleted version of an object, click Restorenext to that object version. The restore object version pane opens.
Click Confirm.

Command line

To restore a soft-deleted version of an object, use the gcloud storage restore command:

gcloud storage restore gs:// BUCKET_NAME 
/ OBJECT_NAME 
# GENERATION_NUMBER

Replace the following:

BUCKET_NAME : the name of the bucket. For example, my-bucket .
OBJECT_NAME : the name of the object for which you want to view all the versions.
GENERATION_NUMBER : the generation number of the soft-deleted object you want to restore. For example, 1560468815691234 . If you don't specify the generation number, the latest version is restored.

For additional options for restoring multiple objects in bulk, including restoring all versions of an object with the all-versions flag, see the gcloud storage restore reference .

REST APIs

JSON API

Have gcloud CLI installed and initialized , which lets you generate an access token for the Authorization header.
Use cURL to call the JSON API with a POST Object request:
```
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/ BUCKET_NAME 
/o/ OBJECT_NAME 
/restore?generation= GENERATION_NUMBER 
"
```
Where:
- BUCKET_NAME is the name of the relevant bucket. For example, my-bucket .
- OBJECT_NAME is the name of the soft-deleted object you want to restore. For example, cat.jpeg .
- GENERATION_NUMBER is the generation number of the soft-deleted object you want to restore. For example, 1560468815691234 .

Bulk restore soft-deleted objects in a bucket

If you want to restore a large number of objects, or don't know the specific objects that you want to restore, use a bulk restore operation. Note that bulk restore operations occur asynchronously and can, in some cases, take an hour or more to begin.

Bulk restore operation initiates a long-running operation on a bucket. You can use the Google Cloud CLI to get and list long-running operations so you can view the details and status of the bulk restore operation while it's in progress.

Use the following instructions to bulk restore soft-deleted objects in a bucket:

Console

In the Google Cloud console, go to the Cloud Storage Buckets page.

Go to Buckets
In the list of buckets, find the bucket that contains the objects you want to restore.
Click the Bucket overflowmenu ( ) associated with the bucket and select Create restore job.

The Create a restore jobpane opens.
In the Choose which soft-deleted objects to restoresection, select the deletion period from which you want to restore objects.
(Optional) Select Filter by glob patternand enter a glob pattern to restore only objects that meet the glob pattern criteria.
(Optional) Toggle additional restore behaviors in the Restore optionssection.
Click Create.

You can track the progress of your bulk restore operation by clicking on the Notificationsbutton ( ) found in the Google Cloud console header.

Command line

To use the bulk restore operation to restore all objects in a bucket, use the gcloud storage restore command.

The following command performs bulk restore operation to asynchronously restore all the objects of the bucket that were deleted during a specific time period:

gcloud storage restore gs:// BUCKET_NAME 
/** \
      --async --deleted-after-time= DELETED_AFTER_TIME 
\
      --deleted-before-time= DELETED_BEFORE_TIME

Replace the following:

BUCKET_NAME : the name of the bucket. For example, my-bucket .
DELETED_AFTER_TIME : an optional argument to specify the date after which the objects are restored. For example, 2022-12-01 .
DELETED_BEFORE_TIME : an optional argument to specify the date before which the objects are restored. For example, 2022-12-21 .

If successful, the command returns the ID of the long-running operation associated with the bulk restore operation. You can get the details of the long-running operation or cancel the long-running operation to stop the bulk restore operation before it completes. For more information, see Use long-running operations .

REST APIs

JSON API

Have gcloud CLI installed and initialized , which lets you generate an access token for the Authorization header.

Use cURL to call the JSON API with a POST Object request:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/ BUCKET_NAME 
/o/bulkRestore"

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

If successful, the command returns the ID of the long-running operation associated with the bulk restore operation. You can get the details of the long-running operation or cancel the long-running operation to stop the bulk restore operation before it completes. For more information, see Use long-running operations .

Use long-running operations for bulk restore

The bulk restore operation initiates a long-running operation . You can get and list long-running operations in order to view the details and status of a bulk restore operation, or delete a long-running operation in order to cancel a bulk restore operation while it's in progress.

For instructions on using long-running operations that get initiated from operations in Cloud Storage, such as the bulk restore operation, see Use long-running operations .

The following example shows a long-running operation that's returned from a bulk restore operation:

 done 
 : 
  
 false 
 { 
  
 "kind" 
 : 
  
 "storage@operation" 
 , 
  
 "name" 
 : 
  
 "projects/_/buckets/my-bucket/operations/CiQyODRlMTY0My0wNGExLTQ3MWItOTE2Zi1hZmQ0ZmM4ZDc4MjQQAg" 
 , 
  
 "metadata" 
 : 
  
 { 
  
 "@type" 
 : 
  
 "type.googleapis.com/google.storage.v2.BulkRestoreObjectsMetadata" 
 , 
  
 "commonMetadata" 
 : 
  
 { 
  
 "type" 
 : 
  
 "bulk-restore-objects" 
 , 
  
 "createTime" 
 : 
  
 "2023-10-20T21:08:11.289Z" 
 , 
  
 "updateTime" 
 : 
  
 "2023-10-20T21:18:37.583Z" 
 , 
  
 "endTime" 
 : 
  
 "2023-10-20T21:18:37.583Z" 
 , 
  
 "requestedCancellation" 
 : 
  
 false 
 , 
  
 "progressPercent" 
 : 
  
 -1 
 , 
  
 }, 
  
 "allow_overwrite" 
 : 
  
 false 
 , 
  
 "matchGlobs" 
 : 
  
 [ 
 "*" 
 ], 
  
 "succeededCount" 
 : 
  
 "0" 
 , 
  
 "failedCount" 
 : 
  
 "0" 
 , 
  
 "skippedCount" 
 : 
  
 "0" 
 , 
  
 }, 
  
 "done" 
 : 
  
 true 
 , 
  
 "response" 
 : 
  
 { 
  
 "@type" 
 : 
  
 "type.googleapis.com/google.storage.v2.BulkRestoreObjectsResponse" 
  
 } 
 }

What's next

Learn more about soft delete .

Use soft-deleted objects Stay organized with collections Save and categorize content based on your preferences.

Before you begin

Required permissions

List all of the soft-deleted objects in a bucket

Console

Command line

REST APIs

JSON API

View all of the soft-deleted versions of an object

Console

Command line

REST APIs

JSON API

Restore a soft-deleted object

Console

Command line

REST APIs

JSON API

Bulk restore soft-deleted objects in a bucket

Console

Command line

REST APIs

JSON API

Use long-running operations for bulk restore

What's next

Use soft-deleted objects