Use object holds

Overview

This page describes how to use object holds, including placing holds by default on new objects and placing holds on individual objects.

Required permissions

Before using this feature in Cloud Storage, you must have sufficient permission to view and update buckets and objects in Cloud Storage:

  • If you own the project that contains the bucket, you most likely have the necessary permissions.

  • If you use IAM, you should have storage.buckets.update, storage.buckets.get, storage.objects.update, and storage.objects.get permissions on the relevant bucket. See Using IAM Permissions for instructions on how to get a role, such as Storage Admin, that has these permissions.

  • If you use ACLs, you should have OWNER permission on the relevant bucket and on the objects within it. See Setting ACLs for instructions on how to do this.

Use the default event-based hold property

The following tasks show you how to set and view the default event-based hold property on a bucket. When this property is enabled, new objects added to the bucket automatically get an event-based hold placed on them.

Set the default event-based hold property

To enable or disable the default event-based hold property for a bucket:

Console

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

    Go to Buckets

  2. In the list of buckets, click the name of the bucket that you want to set the default event-based hold property for.

  3. Select the Protection tab near the top of the page.

    The current status for the bucket appears in the Default event-based hold option section.

  4. In the Default event-based hold option section, click the current status to change it.

    The status appears as either Enabled or Disabled.

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

Command line

Use the gcloud storage buckets update command with the appropriate flag:

gcloud storage buckets update gs://BUCKET_NAME FLAG

Where:

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

  • FLAG is either --default-event-based-hold to enable default event-based object holds or --no-default-event-based-hold to disable them.

Client libraries

C++

For more information, see the Cloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

The following sample enables default event-based holds on a bucket:

The following sample disables default event-based holds on a bucket:

C#

For more information, see the Cloud Storage C# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

The following sample enables default event-based holds on a bucket:

The following sample disables default event-based holds on a bucket:

Go

For more information, see the Cloud Storage Go API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

The following sample enables default event-based holds on a bucket:

The following sample disables default event-based holds on a bucket:

Java

For more information, see the Cloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

The following sample enables default event-based holds on a bucket:

The following sample disables default event-based holds on a bucket:

Node.js

For more information, see the Cloud Storage Node.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

The following sample enables default event-based holds on a bucket:

The following sample disables default event-based holds on a bucket:

PHP

For more information, see the Cloud Storage PHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

The following sample enables default event-based holds on a bucket:

The following sample disables default event-based holds on a bucket:

Python

For more information, see the Cloud Storage Python API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

The following sample enables default event-based holds on a bucket:

The following sample disables default event-based holds on a bucket:

Ruby

For more information, see the Cloud Storage Ruby API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

The following sample enables default event-based holds on a bucket:

The following sample disables default event-based holds on a bucket:

REST APIs

JSON API

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

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

    {
  "defaultEventBasedHold": STATE
}

    Where STATE is either true or false.

  3. Use cURL to call the JSON API with a PATCH 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?fields=defaultEventBasedHold"

    Where:

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

XML API

The XML API cannot be used to work with object holds. Use one of the other Cloud Storage tools, such as the gcloud CLI, instead.

Get the default hold status of a bucket

To view whether a bucket places event-based holds on new objects by default:

Console

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

    Go to Buckets

  2. In the list of buckets, click the name of the bucket that you want to check the default event-based status for.

  3. Select the Protection tab near the top of the page.

  4. The status appears in the Default event-based hold option section.

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

Command line

Use the gcloud storage buckets describe command with the --format flag:

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

Where BUCKET_NAME is the name of the bucket whose status you want to view. For example, my-bucket.

If successful, the response looks similar to the following example:

default_event_based_hold: true

Client libraries

C++

For more information, see the Cloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

C#

For more information, see the Cloud Storage C# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

Go

For more information, see the Cloud Storage Go API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

Java

For more information, see the Cloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

Node.js

For more information, see the Cloud Storage Node.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

PHP

For more information, see the Cloud Storage PHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

Python

For more information, see the Cloud Storage Python API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

Ruby

For more information, see the Cloud Storage Ruby API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

REST APIs

Manage individual object holds

The following tasks show you how to modify and view holds on individual objects.

Place or release an object hold

To place or release a hold on an object in your bucket:

Console

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

    Go to Buckets

  2. In the list of buckets, click the name of the bucket that has the objects you want to place or remove holds on.

  3. Select the checkbox next to the names of objects you want to place or remove holds on.

  4. Click the Manage holds button.

    The Manage holds window appears.

  5. Toggle the checkboxes for each hold type as desired.

  6. Click Save hold settings.

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

Command line

Use the gcloud storage objects update command with the appropriate flag::

gcloud storage objects update gs://BUCKET_NAME/OBJECT_NAME FLAG

Where:

  • BUCKET_NAME is the name of the relevant bucket. For example, my-bucket.
  • OBJECT_NAME is the name of the relevant object. For example, pets/dog.png.

  • FLAG is one of the following:

    • --event-based-hold to enable an event based hold on the object.
    • --no-event-based-hold to disable any event based hold on the object.
    • --temporary-hold to enable a temporary hold on the object.
    • --no-temporary-hold to disable any temporary hold on the object.

See Object holds for more information about hold types.

Client libraries

C++

For more information, see the Cloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

The following sample sets an event-based hold on an object:

The following sample releases an event-based hold on an object:

The following sample sets a temporary hold on an object:

The following sample releases a temporary hold on an object:

C#

For more information, see the Cloud Storage C# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

The following sample sets an event-based hold on an object:

The following sample releases an event-based hold on an object:

The following sample sets a temporary hold on an object:

The following sample releases a temporary hold on an object:

Go

For more information, see the Cloud Storage Go API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

The following sample sets an event-based hold on an object:

The following sample releases an event-based hold on an object:

The following sample sets a temporary hold on an object:

The following sample releases a temporary hold on an object:

Java

For more information, see the Cloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

The following sample sets an event-based hold on an object:

The following sample releases an event-based hold on an object:

The following sample sets a temporary hold on an object:

The following sample releases a temporary hold on an object:

Node.js

For more information, see the Cloud Storage Node.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

The following sample sets an event-based hold on an object:

The following sample releases an event-based hold on an object:

The following sample sets a temporary hold on an object:

The following sample releases a temporary hold on an object:

PHP

For more information, see the Cloud Storage PHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

The following sample sets an event-based hold on an object:

The following sample releases an event-based hold on an object:

The following sample sets a temporary hold on an object:

The following sample releases a temporary hold on an object:

Python

For more information, see the Cloud Storage Python API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

The following sample sets an event-based hold on an object:

The following sample releases an event-based hold on an object:

The following sample sets a temporary hold on an object:

The following sample releases a temporary hold on an object:

Ruby

For more information, see the Cloud Storage Ruby API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

The following sample sets an event-based hold on an object:

The following sample releases an event-based hold on an object:

The following sample sets a temporary hold on an object:

The following sample releases a temporary hold on an object:

REST APIs

JSON API

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

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

    {
  "HOLD_TYPE": STATE
}

    Where:

    • HOLD_TYPE is the type of hold you want to set or release on your object. For example, temporaryHold or eventBasedHold. See Object holds for more information about hold types.
    • STATE is either true to place the hold or false to release the hold.

  3. Use cURL to call the JSON API with a PATCH Object 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/o/OBJECT_NAME"

    Where:

    • JSON_FILE_NAME is the path for the file that you created in Step 2.
    • BUCKET_NAME is the name of the relevant bucket. For example, my-bucket.
    • OBJECT_NAME is the URL-encoded name of the relevant object. For example, pets/dog.png, URL-encoded as pets%2Fdog.png.

XML API

The XML API cannot be used to work with object holds. Use one of the other Cloud Storage tools, such as the gcloud CLI, instead.

Get the hold status for an object

To view what, if any, holds exist on an object, follow the general instructions for viewing object metadata.

What's next

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-18 UTC.