Use long-running operations in Cloud Storage

This page describes how to uselong-running operations that getinitiated from using method calls in Cloud Storage. For detailedinformation about the semantics of a long-running operation that getsreturned from a specific method call, see the feature-specific documentation.

Get required roles

To get the permissions that you need to manage long-running operations inCloud Storage, ask your administrator to grant you theStorage Admin (roles/storage.admin) role or the Storage Legacy Bucket Owner(roles/storage.legacyBucketOwner) role on the bucket or the projectused to perform the underlying operation.

These predefined roles contain the following permissions,which are required to manage long-running operations in Cloud Storage:

  • storage.bucketOperations.cancel
  • storage.bucketOperations.get
  • storage.bucketOperations.list
  • storage.buckets.list (this permission is required only when using the Google Cloud console)
Note: The user who initiates a long-running operation can always get the detailsof the long-running operation, regardless of whether or not they have thestorage.bucketOperations.get IAM permission. Users who didnot initiate the long-running operation must have thestorage.bucketOperations.get in order to get the details of the long-runningoperation. Thestorage.bucketOperations.list andstorage.bucketOperations.cancel permissions are always required in orderto list and cancel long-running operations.

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

Get the details of a long-running operation

Console

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

    Go to Buckets

  2. In the bucket list, click the name of the bucket associated with thelong-running operation.

  3. Click theOperations tab.

Command line

Note: The Google Cloud CLI automatically specifies a default project, whichcan be controlled using the--project flag.

To get the details or check the status of a long-running operation, use thegcloud storage operations describe command:

gcloud storage operations describe projects/_/buckets/BUCKET_NAME/operations/OPERATION_ID

Replace:

  • BUCKET_NAME with the name of the bucket that containsthe long-running operation. For example,my-bucket.

  • OPERATION_ID with the ID of the long-runningoperation, which is returned in the response of methods you call. Forexample, the following response is returned from callinggcloud storage restore and the long-running operation ID isBcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP:

    Created: projects/_/buckets/my-bucket/operations/BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP

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 anoperations.get request:

    curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \"https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/operations/OPERATION_ID"

    Replace:

    • BUCKET_NAME with the name of the bucketassociated with the long-running operation.

    • OPERATION_ID with the ID of thelong-running operation, which is returned in the response ofmethods you call. For example, the following response is returnedfrom callinggcloud storage restore and the long-runningoperation ID isBcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP:

      Created: projects/_/buckets/my-bucket/operations/BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP

If the request is successful, anoperations resource isreturned:

{  "kind": "storage#operation",  "name": "projects/_/buckets/bucket/operations/operation_id",  "metadata": {    "@type": OperationMetadataType*,    metadata OperationMetadata*  },  "done": boolean,  "response": {    "@type": ResponseResourceType*,    response ResponseResource*  }}

List the long-running operations in a bucket

Console

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

    Go to Buckets

  2. In the bucket list, click the name of the bucket.

  3. Click theOperations tab.

Command line

To list the long-running operations in a bucket, use thegcloud storage operations list command:

gcloud storage operations list gs://BUCKET_NAME

Replace:

  • BUCKET_NAME with the name of the bucket thatcontains the long-running operations. For example,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 anoperations.get request:

    curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \"https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/operations"

    Replace:

    • BUCKET_NAME with the name of the bucketassociated with the long-running operations you want to list.

If the request is successful, you get a response similar to thefollowing:

{  "kind": "storage#operations",  "nextPageToken": string,  "operations": [    operations Resource  ]}

Cancel a long-running operation

Note: Cancelling a long-running operation is asynchronous and done atbest-effort. A cancel request on a running long-running operation sets therequested cancellation field, but there's no guarantee that the request willbe honored.

Console

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

    Go to Buckets

  2. In the bucket list, click the name of the bucket associated with thelong-running operation that you want to cancel.

  3. Click theOperations tab.

  4. In the row for the long-running operation, clickMore options, and thenclickCancel.

Command line

Note: The Google Cloud CLI automatically specifies a default project, whichcan be controlled using the--project flag.

To cancel a long-running operation, use thegcloud storage operations cancel command:

gcloud storage operations cancel projects/_/buckets/BUCKET_NAME/operations/OPERATION_ID

Replace:

  • BUCKET_NAME with the name of the bucket that containsthe long-running operation. For example,my-bucket.

  • OPERATION_ID with the ID of the long-runningoperation, which is returned in the response of methods you call. Forexample, the following response is returned from callinggcloud storage restore and the long-running operation ID isBcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP:

    Created: projects/_/buckets/my-bucket/operations/BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP

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 anoperations.post request:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \"https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/operations/OPERATION_ID/cancel"

    Replace:

    • BUCKET_NAME with the name of the bucketassociated with the long-running operation you want to cancel.

    • OPERATION_ID with the ID of thelong-running operation, which is returned in the response ofmethods you call. For example, the following response is returnedfrom callinggcloud storage restore and the long-runningoperation ID isBcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP:

      Created: projects/_/buckets/my-bucket/operations/BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP

Metadata

Long-running operations have metadata associated with them. The followingmetadata identify properties of a long-running operation:

  • Create time: The time the long-running operation was created.

  • End time: The time the long-running operation finished running.

  • Update time: The time the long-running operation was last modified.

  • Type: The API call that initiated the long-running operation.

  • Requested cancellation: Indicates whether the user has requested cancellationof the long-running operation.

  • Progress percent: The estimated progress of the long-running operation,in percentage. A value of-1 means the progress is unknown.

In the Google Cloud console, the progress percent and requested cancellationmetadata are displayed in a combinedStatus field.

Error handling

Long-running operations are initiated from asynchronous APIs and requiredifferent error handling practices than synchronous APIs. Unlike synchronousAPIs, the response to asynchronous API calls can indicate success even if thelong-running operation eventually fails. Instead of relying on the statuscode that gets returned in the response headers, you should parse thelong-running operation metadata in the body of the response to determinewhether an API call was successful.

For example, if you make a soft delete bulk restore request, it returns asuccessful HTTP status code (200 OK) even if an error occurs over the courseof the operation. To check whether the bulk restore operation was successful,get the status of the long-running operation.

Note that the long-running operation APIs (Get, List, Cancel) aresynchronous and return normal errors.

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.