Yandex Cloud
Search
Contact UsGet started
  • Pricing
  • Customer Stories
  • Documentation
  • Blog
  • All Services
  • System Status
    • Featured
    • Infrastructure & Network
    • Data Platform
    • Containers
    • Developer tools
    • Serverless
    • Security
    • Monitoring & Resources
    • AI Studio
    • Business tools
  • All Solutions
    • By industry
    • By use case
    • Economics and Pricing
    • Security
    • Technical Support
    • Start testing with double trial credits
    • Cloud credits to scale your IT product
    • Gateway to Russia
    • Cloud for Startups
    • Education and Science
    • Yandex Cloud Partner program
  • Pricing
  • Customer Stories
  • Documentation
  • Blog
© 2025 Direct Cursus Technology L.L.C.
Yandex Cloud API concepts
  • Basic principles
    • Overview
    • Asynchronous operations
    • Operation object
    • Idempotency

In this article:

  • Operation object format
  • Operation status monitoring
  • Canceling an operation
  • Viewing a list of operations
  1. Working with operations
  2. Operation object

Operation object

Written by
Yandex Cloud
Improved by
Dmitry A.
Updated at April 23, 2025
  • Operation object format
  • Operation status monitoring
  • Canceling an operation
  • Viewing a list of operations

Each operation that changes the state of a resource causes an Operation object to be created. This object contains information about the operation: its status, ID, call time, and so on.

With the Operation object, you can:

  • Monitor the status of operations with indefinite duration. For example, starting a VM or attaching a disk.
  • Cancel operations.
  • View a list of operations that were performed on the specified resource.

Operation object formatOperation object format

The Operation object contains the following fields:

Field Description
id* string
Operation ID. Generated on the service side.
created_at* google.protobuf.Timestamp
Operation start time. Uses RFC3339 (Timestamps) format.
created_by* string
ID of the user who started the operation.
modified_at* google.protobuf.Timestamp
Resource last update time. Uses RFC3339 (Timestamps) format.
done* bool
Operation status. Can take one of the two values:
true for operation completed. Note that the operation is considered completed even if there was an error during its execution.
false for operation not completed.
response google.protobuf.Any
This field is present only if the operation was completed successfully.

For the Create and Update methods, the response field contains a view of the created or updated resource. For other operations, the field may contain an empty message (google.protobuf.Empty), e.g., when deleting a resource.

The response and error fields are mutually exclusive. A response cannot contain both fields at the same time.
error google.rpc.Status
Error message. This field is present if an error occurs during the operation.


The error field may appear in the response before the operation is completed: when an error occurs, the service immediately adds the error field to the Operation object. At the same time, the service starts rolling back to the previous state: it aborts all running procedures and deletes the resources created during the operation. Only when the service returns to the previous state, the operation will be considered completed and its done field will be set to true.

The response and error fields are mutually exclusive. A response cannot contain both fields at the same time.
metadata google.protobuf.Any
Operation metadata. This field usually contains the ID of the resource the operation is being performed on. If the method returns the Operation object, the method description contains the structure of the corresponding metadata field.
description string
Operation description. The maximum length is 256 characters.

* This is a required field.

Operation status monitoringOperation status monitoring

To find out the operation status, use the Get method:

 // Returns the Operation object by the specified ID.
 rpc Get (GetOperationRequest) returns (operation.Operation) {
   option (google.api.http) = {
     get: "/operations/{operation_id}"
   };
 }
 message GetOperationRequest {
   // Operation ID.
   string operation_id = 1;
 }

Sample REST request used to get the operation status:

GET https://operation.api.cloud.yandex.net/operations/fcmq0j5033e516c56ctq

Canceling an operationCanceling an operation

To cancel an operation, use the Cancel method:

 // Cancels the specified operation.
 rpc Cancel (CancelOperationRequest) returns (operation.Operation) {
   option (google.api.http) = {
     post: "/operations/{operation_id}:cancel"
   };
 }
 message CancelOperationRequest {
   // ID of the operation to cancel.
   string operation_id = 1;
 }

Example of canceling an operation in the REST API:

POST https://operation.api.cloud.yandex.net/operations/a3s17h9sbq5asdgss12:cancel

In response, the server will return the Operation object with the current status of the operation being canceled.

You can only cancel operations that change the state of a resource. In the references, all operations that can be canceled are marked explicitly.

Note

The Cancel method works on a best effort basis. Calling the method does not guarantee that the operation will be canceled. The operation may be at a stage when cancellation is no longer possible.

Viewing a list of operationsViewing a list of operations

To view a list of operations that were performed on a given resource, use the ListOperations method. The method supports result pagination.

Note that the ListOperations method returns a list of operations only for a specific resource, not resource category. For example, you cannot view the history of operations performed on all disks in your cloud.

Sample gRPC description of the ListOperations method for viewing a list of operations performed on a disk:

 // Returns a list of operations performed on the specified disk.
 rpc ListOperations (ListDiskOperationsRequest)
   returns (ListDiskOperationsResponse) {
     option (google.api.http) = {
       get: "/compute/v1/disks/{disk_id}/operations"
     };
   }
 message ListDiskOperationsRequest {
   // Disk ID.
   string disk_id = 1;
   // Maximum number of results per response page.
   int64 page_size = 2;
   // Token of the requested result page.
   string page_token = 3;
 }

 message ListDiskOperationsResponse {
   // List of operations performed on the specified disk.
   repeated operation.Operation operations = 1;
   // Token for the next result page.
   string next_page_token = 2;
 }

The maximum page_size field value is 1000.

Sample REST request for a list of operations:

GET https://compute.api.cloud.yandex.net/compute/v1/disks/e0m97h0gbq0foeuis03/operations

Server response:

 {
   "operations": [
     {
       "id": "fcmq0j5033e516c56ctq",
       "createdAt": "2018-08-29T18:31:15.311Z",
       "createdBy": "v1swrh5sbqs5sdgss15",
       "done": true,
       "metadata": {
         "@type": "type.googleapis.com/yandex.cloud.compute.v1.CreateDiskMetadata",
         "diskId": "sfg36d6sbq5asdgfs01"
       },
      "response": {
        "@type": "type.googleapis.com/yandex.cloud.compute.v1.Disk",
        "id": "sfg36d6sbq5asdgfs01",
        "folderId": "a3s17h9sbq5asdgss12",
        "name": "disk-1",
        "description": "Test disk",
        "zoneId" : "ru-central1-a",
        "typeId" : "network-nvme",
        "size" : 10737418240
      }
    },
    ...
   ]
 }

Was the article helpful?

Previous
Asynchronous operations
Next
Idempotency
© 2025 Direct Cursus Technology L.L.C.