Monitor long-running operations

This page describes how to manage the lifecycle of a long-running operation (LRO) in Google Agentspace.

A long-running operation object is returned when a call to a method might take a long time to complete. For example, the Agentspace API creates a long-running operation when you call documents.import through the API or Client Libraries. The operation tracks the status of the processing job.

You can use the long-running operations methods that the Agentspace API provides to check the status of the operations. You can also list or poll operations.

The record of an operation is kept for approximately 30 days after the operation finishes, meaning that you can't view or list an operation after that time.

List long-running operations

The following show how to list the operations for a Google Cloud resource.

REST

To list the long-running operations for a Google Cloud resource, follow this step:

Call the operations.list method:

 curl  
-X  
GET  
 \ 
  
-H  
 "Authorization: Bearer 
 $( 
gcloud  
auth  
print-access-token ) 
 " 
  
 \ 
  
 "https://discoveryengine.googleapis.com/v1/projects/ PROJECT_ID 
/locations/global/collections/default_collection/dataStores/ DATA_STORE_ID 
/operations"

DATA_STORE_ID : The ID of the Agentspace data store that was created with your engine. In the Google Cloud console URL, the data store ID appears after engines/ and before /data .

Python

Before trying this sample, follow the Python setup instructions in the Agentspace quickstart using client libraries . For more information, see the Agentspace Python API reference documentation .

To authenticate to Agentspace, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .

  from 
  
 typing 
  
 import 
 Optional 
 from 
  
 google.cloud 
  
 import 
 discoveryengine 
 from 
  
 google.longrunning 
  
 import 
 operations_pb2 
 # TODO(developer): Uncomment these variables before running the sample. 
 # project_id = "YOUR_PROJECT_ID" 
 # location = "YOUR_PROCESSOR_LOCATION"  # Options: "global" 
 # search_engine_id = "YOUR_SEARCH_ENGINE_ID" 
 # Create filter in https://google.aip.dev/160 syntax 
 # operations_filter = "YOUR_FILTER" 
 def 
  
 list_operations_sample 
 ( 
 project_id 
 : 
 str 
 , 
 location 
 : 
 str 
 , 
 search_engine_id 
 : 
 str 
 , 
 operations_filter 
 : 
 Optional 
 [ 
 str 
 ] 
 = 
 None 
 , 
 ) 
 - 
> operations_pb2 
 . 
 ListOperationsResponse 
 : 
 # Create a client 
 client 
 = 
 discoveryengine 
 . 
  DocumentServiceClient 
 
 () 
 # The full resource name of the search engine branch. 
 name 
 = 
 f 
 "projects/ 
 { 
 project_id 
 } 
 /locations/ 
 { 
 location 
 } 
 /collections/default_collection/dataStores/ 
 { 
 search_engine_id 
 } 
 " 
 # Make ListOperations request 
 request 
 = 
 operations_pb2 
 . 
 ListOperationsRequest 
 ( 
 name 
 = 
 name 
 , 
 filter 
 = 
 operations_filter 
 , 
 ) 
 # Make ListOperations request 
 response 
 = 
 client 
 . 
  list_operations 
 
 ( 
 request 
 = 
 request 
 ) 
 # Print the Operation Information 
 for 
 operation 
 in 
 response 
 . 
 operations 
 : 
 print 
 ( 
 operation 
 ) 
 return 
 response

Get details about a long-running operation

The following show how to get details about an operation.

REST

To get the status of and view details about a long-running operation, follow these steps:

Find the name of the operation in one of two ways:

After you've made a call to a method that returns a long-running operation, review the response.

For example, if you call documents.import , the start of the response looks something like this:

  { 
  
 "operations" 
 : 
  
 [ 
  
 { 
  
 "name" 
 : 
  
 "projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789" 
 , 
  
 "metadata" 
 : 
  
 { 
  
 "@type" 
 : 
  
 "type.googleapis.com/google.cloud.discoveryengine.v1.ImportDocumentsMetadata" 
 , 
  
 } 
  
 } 
  
 ] 
 }

The name value in the response provides the operation name, which can be used to query the operation status. Don't include the quotes when you copy the operation name.

Get the operation name by listing long-running operations .

Call the operations.get method on the resource that created the operation:

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

OPERATION_NAME : Provide the name of the operation for which you need information. You can find the operation name by listing long-running operations .

The first lines of the response from the GET command look something like this:

  { 
  
 "name" 
 : 
  
 "projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789" 
 , 
  
 "metadata" 
 : 
  
 { 
  
 "@type" 
 : 
  
 "type.googleapis.com/google.cloud.discoveryengine.v1.ImportDocumentsMetadata" 
  
 } 
  
 }

Python

Before trying this sample, follow the Python setup instructions in the Agentspace quickstart using client libraries . For more information, see the Agentspace Python API reference documentation .

To authenticate to Agentspace, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .

  from 
  
 google.cloud 
  
 import 
 discoveryengine 
 from 
  
 google.longrunning 
  
 import 
 operations_pb2 
 # TODO(developer): Uncomment these variables before running the sample. 
 # Example: `projects/{project}/locations/{location}/collections/{default_collection}/dataStores/{search_engine_id}/branches/{0}/operations/{operation_id}` 
 # operation_name = "YOUR_OPERATION_NAME" 
 def 
  
 get_operation_sample 
 ( 
 operation_name 
 : 
 str 
 ) 
 - 
> operations_pb2 
 . 
 Operation 
 : 
 # Create a client 
 client 
 = 
 discoveryengine 
 . 
 DocumentServiceClient 
 () 
 # Make GetOperation request 
 request 
 = 
 operations_pb2 
 . 
 GetOperationRequest 
 ( 
 name 
 = 
 operation_name 
 ) 
 operation 
 = 
 client 
 . 
 get_operation 
 ( 
 request 
 = 
 request 
 ) 
 # Print the Operation Information 
 print 
 ( 
 operation 
 ) 
 return 
 operation

Poll a long-running operation

The following show how to poll the status of an operation.

REST

To poll the long-running operation until it finishes, follow these steps:

Run the following command, which calls the operations.get method repeatedly, using a backoff of 10 seconds between each request:
```
  while 
  
true ; 
  
 \ 
  
 do 
  
curl  
-X  
GET  
 \ 
  
-H  
 "Authorization: Bearer 
 $( 
gcloud  
auth  
print-access-token ) 
 " 
  
 \ 
  
 "https://discoveryengine.googleapis.com/v1/ OPERATION_NAME 
" 
 ; 
  
 \ 
  
sleep  
 10 
 ; 
  
 \ 
  
 done 
 
```
OPERATION_NAME : Provide the name of the operation you want to poll. You can find the operation name by listing long-running operations . For example, projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789 .
Stop the polling job ( Control+Z ) after the status shows "done": true .

Python

Before trying this sample, follow the Python setup instructions in the Agentspace quickstart using client libraries . For more information, see the Agentspace Python API reference documentation .

To authenticate to Agentspace, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .

  from 
  
 time 
  
 import 
 sleep 
 from 
  
 google.cloud 
  
 import 
 discoveryengine 
 from 
  
 google.longrunning 
  
 import 
 operations_pb2 
 # TODO(developer): Uncomment these variables before running the sample. 
 # Example: `projects/{project}/locations/{location}/collections/{default_collection}/dataStores/{search_engine_id}/branches/{0}/operations/{operation_id}` 
 # operation_name = "YOUR_OPERATION_NAME" 
 def 
  
 poll_operation_sample 
 ( 
 operation_name 
 : 
 str 
 , 
 limit 
 : 
 int 
 = 
 10 
 ) 
 - 
> operations_pb2 
 . 
 Operation 
 : 
 # Create a client 
 client 
 = 
 discoveryengine 
 . 
  DocumentServiceClient 
 
 () 
 # Make GetOperation request 
 request 
 = 
 operations_pb2 
 . 
 GetOperationRequest 
 ( 
 name 
 = 
 operation_name 
 ) 
 for 
 _ 
 in 
 range 
 ( 
 limit 
 ): 
 operation 
 = 
 client 
 . 
  get_operation 
 
 ( 
 request 
 = 
 request 
 ) 
 # Print the Operation Information 
 print 
 ( 
 operation 
 ) 
 # Stop polling when Operation is no longer running 
 if 
 operation 
 . 
 done 
 : 
 break 
 # Wait 10 seconds before polling again 
 sleep 
 ( 
 10 
 ) 
 return 
 operation

Cancel a long-running operation

The following shows how to cancel an operation:

REST

To cancel a long-running operation, follow these steps:

Call the operations.cancel method:

 curl  
-X  
post  
 \ 
  
-H  
 "Authorization: Bearer 
 $( 
gcloud  
auth  
print-access-token ) 
 " 
  
 \ 
  
 "https://discoveryengine.googleapis.com/v1/ OPERATION_NAME 
" 
:cancel

OPERATION_NAME : Provide the name of the operation you want to cancel. You can find the operation name by listing long-running operations . For example, projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789 .

After the API call is made, the server attempts to cancel the operation. The results you see and the actions you can take are as follows:

An error with "code": 400 and "status": "FAILED_PRECONDITION" indicates that the request couldn't be canceled.

A successful cancellation results in an empty JSON object. To verify the cancellation:

Use the operations.get method.

If the operation is successfully cancelled, the response from the operations.get method has the error "code": 1 , which represents the CANCELLED status code.

For example:

  { 
  
 "name" 
:  
 "projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789" 
,  
 "metadata" 
:  
 { 
  
 "@type" 
:  
 "type.googleapis.com/google.cloud.discoveryengine.v1alpha.ImportDocumentsMetadata" 
,  
 "createTime" 
:  
 "2025-04-28T21:29:21.199190Z" 
,  
 "updateTime" 
:  
 "2025-04-28T21:31:29.076865Z" 
  
 } 
,  
 "done" 
:  
true,  
 "error" 
:  
 { 
  
 "code" 
:  
 1 
,  
 "message" 
:  
 "Operation projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789 is cancelled." 
  
 } 
 }

Python

Before trying this sample, follow the Python setup instructions in the Agentspace quickstart using client libraries . For more information, see the Agentspace Python API reference documentation .

To authenticate to Agentspace, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .

  from 
  
 google.cloud 
  
 import 
 discoveryengine 
 from 
  
 google.longrunning 
  
 import 
 operations_pb2 
 # TODO(developer): Uncomment these variables before running the sample. 
 # Example: `projects/{project}/locations/{location}/collections/{default_collection}/dataStores/{search_engine_id}/branches/{0}/operations/{operation_id}` 
 # operation_name = "YOUR_OPERATION_NAME" 
 def 
  
 cancel_operation_sample 
 ( 
 operation_name 
 : 
 str 
 ) 
 - 
> None 
 : 
 # Create a client 
 client 
 = 
 discoveryengine 
 . 
  DocumentServiceClient 
 
 () 
 # Make CancelOperation request 
 request 
 = 
 operations_pb2 
 . 
 CancelOperationRequest 
 ( 
 name 
 = 
 operation_name 
 ) 
 client 
 . 
  cancel_operation 
 
 ( 
 request 
 = 
 request 
 ) 
 return

Monitor long-running operations Stay organized with collections Save and categorize content based on your preferences.

List long-running operations

REST

Python

Get details about a long-running operation

REST

Python

Poll a long-running operation

REST

Python

Cancel a long-running operation

REST

Python

Monitor long-running operations