Set and manage soft delete policies

OverviewUsage

This page describes how to set and managesoft delete policies.You can set new policies on buckets to enable soft delete, as well asupdate and check the status of existing policies. To learn how to disablesoft delete, seeDisable soft delete.

To learn how to list and restore soft-deleted objects, seeUse soft-deleted objects. To learn how to list and restoresoft-deleted buckets, seeUse soft-deleted buckets.

Required roles

To get the permissions that you need to enable and manage soft delete policies, ask your administrator to grant you theStorage Admin (roles/storage.admin) IAM role on the bucket or the project that contains the bucket.

This predefined role contains the permissions required to enable and manage soft delete policies. To see the exact permissions that are required, expand theRequired permissions section:

Required permissions

The following permissions are required to enable and manage soft delete policies:

  • storage.buckets.get
  • storage.buckets.update
  • storage.buckets.list (this permission is only required if you plan to use the Google Cloud console to perform the instructions on this page)

For information about granting roles, seeSet and manage IAM policies on buckets orManage access to projects.

Edit a bucket's soft delete policy

The new soft delete retention duration onlyapplies to objects or buckets that you delete after thesoft delete policy takes effect. Existing soft-deleted objects aren'taffected by updates made to the soft delete policy and are retainedfor the duration that was in effect when they were deleted.

Use the following instructions to edit a bucket's soft deletepolicy:

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 whosesoft delete policy you want to edit.

  3. Click theProtection tab.

  4. In theSoft delete policy (for data recovery) section, add a newsoft delete policy or edit theretention duration ofan existing policy by using the following steps:

    1. ClickEdit.

    2. In theSet a soft delete policy dialogue that appears, specifyasoft delete retention duration by choosing a unitof time and a length of time.

    3. ClickSave.

To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, seeTroubleshooting.

Command line

To add or edit the soft delete policy on a bucket, use thegcloud storage buckets update command with the--soft-delete-duration flag:

  gcloud storage buckets update gs://BUCKET_NAME --soft-delete-duration=SOFT_DELETE_DURATION

Where:

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

  • SOFT_DELETE_DURATION specifies thesoft delete retention duration.

    • The units represents seconds.
    • The unitd represents days.
    • The unitm represents months.

    For example:

    • 7d43200s sets a retention duration of seven and a half days(7 days and 43,200 seconds).

    • 2w1d sets a retention duration of two weeks and one day.

REST APIs

JSON API

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

  2. Create a JSON file that contains the following information:

    {"softDeletePolicy":{"retentionDurationSeconds":"TIME_IN_SECONDS"}}

    WhereTIME_IN_SECONDS is the amount oftime in seconds you want to set thesoft delete retention duration to. Forexample,2678400 for 2,678,400 seconds (31 days).

  3. UsecURL to call theJSON API with aPATCH Bucket request:

    curl -X PATCH --data-binary @JSON_FILE_NAME \  -H "Authorization: Bearer $(gcloud auth print-access-token)" \  -H "Content-Type: application/json" \  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME"

    Where:

    • JSON_FILE_NAME is the path for the JSONfile that you created in Step 2.
    • BUCKET_NAME is the name of the relevantbucket. For example,my-bucket.

Check if the soft delete policy is enabled on a 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 whosesoft delete policy you want to check.

  3. Click theProtection tab.

    The status displays in theSoft delete policy (for data recovery)section.

You can also use theProtection tab to check if there's asoft delete policy on your bucket.

To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, seeTroubleshooting.

Command line

To check the soft delete policy status of a bucket, use thegcloud storage buckets describe command:

  gcloud storage buckets describe gs://BUCKET_NAME \      --format="default(soft_delete_policy)"

Where:

  • BUCKET_NAME is 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 aGET Bucket request:

    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?fields=softDeletePolicy"

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

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.