Use soft-deleted objects

OverviewSetup

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 theStorage 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 theRequired permissions section:

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, seeSet and manage IAM policies on buckets. For information about granting roleson projects, seeManage access to projects.

In order to managelong-running operations that get initiated fromsoft delete methods, you might need additional roles and permissions.Seerequired 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 abucket:

Console

  1. In the Google Cloud console, go to the Cloud StorageBuckets page.

    Go to Buckets

  2. In the list of buckets, click the name of the bucket you want to viewthe soft-deleted objects of.TheBucket details page opens with theObjects tab selected.

  3. In theShow list, selectSoft-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 thegcloud storage ls command with the--soft-deleted flag and the** wildcard. Note that you might need to surround the wildcardexpression with quotes.

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

Replace the following:

  • BUCKET_NAME: the name of the bucket. Forexample,my-bucket.

REST APIs

JSON API

  1. Have gcloud CLIinstalled and initialized, which lets you generate an access token for theAuthorization header.

  2. UsecURL to call theJSON API with arequest to list objects that uses the?softDeleted queryparameter:

    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"

    WhereBUCKET_NAME is the name of therelevant 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 aspecific object in your bucket:

Console

  1. In the Google Cloud console, go to the Cloud StorageBuckets page.

    Go to Buckets

  2. In the list of buckets, click the name of the bucket that contains theobject you want to view soft-deleted versions of.TheBucket details page opens with theObjects tab selected.

  3. Click the object that you want to view all the soft-deleted versions of.TheObject details page displays.

  4. Click theVersion History tab.

  5. In theShow list, selectSoft-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 abucket, use thegcloud storage ls command:

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

Replace the following:

  • BUCKET_NAME: the name of the bucket. Forexample,my-bucket.
  • OBJECT_NAME: the name of the objectyou want to view all the versions of.

REST APIs

JSON API

  1. Have gcloud CLIinstalled and initialized, which lets you generate an access token for theAuthorization header.

  2. UsecURL to call theJSON API with arequest to list objects that uses the?softDeleted queryparameter:

    curl -X GET \  -H "Authorization: BearerOAUTH2_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. Forexample,my-bucket.
    • OBJECT_NAME: the name of the object forwhich you want to view all versions.

Restore a soft-deleted object

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

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

Console

  1. In the Google Cloud console, go to the Cloud StorageBuckets page.

    Go to Buckets

  2. In the list of buckets, click the name of the bucket that contains thesoft-deleted objects that you want to restore.TheBucket details page opens with theObjects tab selected.

  3. In theShow list, selectSoft-deleted objects only.

  4. Navigate to the object, which may be located in a folder.

  5. Click the soft-deleted object.TheObject details page displays.

  6. In theShow list, selectSoft-deleted objects only.A list of all the soft-deleted versions of that object displays.

  7. To restore a specific soft-deleted version of an object,clickRestore next to that object version.The restore object version pane opens.

  8. ClickConfirm.

Command line

To restore a soft-deleted version of an object, usethegcloud storage restore command:

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

Replace the following:

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

For additional options for restoring multiple objects in bulk, includingrestoring all versions of an object with theall-versions flag, see thegcloud storage restore reference.

REST APIs

JSON API

  1. Have gcloud CLIinstalled and initialized, which lets you generate an access token for theAuthorization header.

  2. UsecURL to call theJSON API with aPOST 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 relevantbucket. For example,my-bucket.
    • OBJECT_NAME is the name of thesoft-deleted object you want to restore. For example,cat.jpeg.
    • GENERATION_NUMBER is the generation numberof the soft-deleted object you want to restore. Forexample,1560468815691234.

Bulk restore soft-deleted objects in a bucket

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

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

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

Console

  1. In the Google Cloud console, go to the Cloud StorageBuckets page.

    Go to Buckets

  2. In the list of buckets, find the bucket that contains the objects youwant to restore.

  3. Click theBucket overflow menu() associatedwith the bucket and selectCreate restore job.

    TheCreate a restore job pane opens.

  4. In theChoose which soft-deleted objects to restore section, selectthe time range that you want to restore objects from.

  5. Optional: To restore only the objects that match aglob pattern,selectFilter by glob pattern and then enter a glob pattern.

  6. Optional: Specify additional restore behaviors in theRestore options section.

  7. ClickCreate.

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

Command line

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

For example, the following command performs bulk restore operation toasynchronously restore all the objects of the bucket that were deletedduring 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. Forexample,my-bucket.
  • DELETED_AFTER_TIME: an optional argument tospecify the date after which the objects are restored. For example,2022-12-01.
  • DELETED_BEFORE_TIME: an optional argument tospecify the date before which the objects are restored. For example,2022-12-21.

For additional options that you can use to filter the objects to be bulkrestored, see thegcloud storage restore reference.

If successful, the command returns the ID of the long-running operationassociated with the bulk restore operation. You can get the detailsof the long-running operation or cancel the long-running operation tostop the bulk restore operation before it completes. For more information,seeUse long-running operations.

REST APIs

JSON API

  1. Have gcloud CLIinstalled and initialized, which lets you generate an access token for theAuthorization header.

  2. UsecURL to call theJSON API with aPOST 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"

    WhereBUCKET_NAME is the name of therelevant bucket. For example,my-bucket.

If successful, the command returns the ID of the long-running operationassociated with the bulk restore operation. You can get the detailsof the long-running operation or cancel the long-running operation tostop the bulk restore operation before it completes. For moreinformation, seeUse long-running operations.

Use long-running operations for bulk restore

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

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

The following example shows a long-running operation that's returned from abulk 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

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 2026-02-19 UTC.