Managing long-running operations (LROs)

Long-Running Operations are returned by batchprocessing method calls because they take a longer time to complete than is appropriatefor an API response. This is so the calling thread is not held open while manydocuments are processed. The Document AI API creates an LRO every time youcallprojects.locations.processors.batchProcessthrough the API or Client Libraries. The LRO tracks the status of the processing job.

You can use theoperations methodsthat the Document AI API provides to check thestatus of LROs. You canalsolist,poll,orcancel LROs. Client libraries callingasync method poll internally, enabling callback. (For Python,await is enabled.) They alsofeature a timeout parameter. Within the main LRO returned by .batchProcess, an LROis created for each document (because batch page-count limits are much higher thanthe syncprocess call and can take significant time to process). When the mainLRO ends, the detailed status of each document LRO is provided.

LROs are managed at the Google Cloud project and location level.When making a request to the API, include the Google Cloud projectand the location in which the LRO is running.

The record of an LRO is kept for approximately 30 days after the LROfinishes, meaning that you cannot view or list an LRO after that point.

Getting details about a long-running operation

The following samples show how to get details about an LRO.

REST

To get the status of and view details about an LRO, call theprojects.locations.operations.get method.

Suppose that you receive the following response after callingprojects.locations.processors.batchProcess:

{  "name": "projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID"}

Thename value in the response shows that the Document AI APIcreated an LRO namedprojects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID.

You can also retrieve the LRO name bylisting long-running operations.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: Your Google Cloud project ID.
  • LOCATION: thelocation where the LRO is running, for example:
    • us - United States
    • eu - European Union
  • OPERATION_ID: The ID of your operation. The ID is the last element of the nameof your operation. For example:
    • Operation name:projects/PROJECT_ID/locations/LOCATION/operations/bc4e1d412863e626
    • Operation id:bc4e1d412863e626

HTTP method and URL:

GET https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID

To send your request, choose one of these options:

curl

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login , or by usingCloud Shell, which automatically logs you into thegcloud CLI . You can check the currently active account by runninggcloud auth list.

Execute the following command:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID"

PowerShell

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login . You can check the currently active account by runninggcloud auth list.

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",  "metadata": {    "@type": "type.googleapis.com/google.cloud.documentai.v1.BatchProcessMetadata",    "state": "SUCCEEDED",    "stateMessage": "Processed 1 document(s) successfully",    "createTime": "TIMESTAMP",    "updateTime": "TIMESTAMP",    "individualProcessStatuses": [      {        "inputGcsSource": "INPUT_BUCKET_FOLDER/DOCUMENT1.ext",        "status": {},        "outputGcsDestination": "OUTPUT_BUCKET_FOLDER/OPERATION_ID/0",        "humanReviewStatus": {          "state": "ERROR",          "stateMessage": "Sharded document protos are not supported for human review."        }      }    ]  },  "done": true,  "response": {    "@type": "type.googleapis.com/google.cloud.documentai.v1.BatchProcessResponse"  }}

Go

For more information, see theDocument AIGo API reference documentation.

To authenticate to Document AI, set up Application Default Credentials. For more information, seeSet up authentication for a local development environment.

packagemainimport("context"documentai"cloud.google.com/go/documentai/apiv1"longrunningpb"cloud.google.com/go/longrunning/autogen/longrunningpb")funcmain(){ctx:=context.Background()// This snippet has been automatically generated and should be regarded as a code template only.// It will require modifications to work:// - It may require correct/in-range values for request initialization.// - It may require specifying regional endpoints when creating the service client as shown in://   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Optionsc,err:=documentai.NewDocumentProcessorClient(ctx)iferr!=nil{// TODO: Handle error.}deferc.Close()req:=&longrunningpb.GetOperationRequest{// TODO: Fill request struct fields.// See https://pkg.go.dev/cloud.google.com/go/longrunning/autogen/longrunningpb#GetOperationRequest.}resp,err:=c.GetOperation(ctx,req)iferr!=nil{// TODO: Handle error.}// TODO: Use resp._=resp}

Python

For more information, see theDocument AIPython API reference documentation.

To authenticate to Document AI, set up Application Default Credentials. For more information, seeSet up authentication for a local development environment.

fromgoogle.api_core.client_optionsimportClientOptionsfromgoogle.cloudimportdocumentai# type: ignorefromgoogle.longrunning.operations_pb2importGetOperationRequest# type: ignore# TODO(developer): Uncomment these variables before running the sample.# location = "YOUR_PROCESSOR_LOCATION"  # Format is "us" or "eu"# operation_name = "YOUR_OPERATION_NAME"  # Format is "projects/{project_id}/locations/{location}/operations/{operation_id}"defget_operation_sample(location:str,operation_name:str)->None:# You must set the `api_endpoint` if you use a location other than "us".opts=ClientOptions(api_endpoint=f"{location}-documentai.googleapis.com")client=documentai.DocumentProcessorServiceClient(client_options=opts)request=GetOperationRequest(name=operation_name)# Make GetOperation requestoperation=client.get_operation(request=request)# Print the Operation Informationprint(operation)

Listing long-running operations

The following samples show how to list the LROs in a Google Cloud project and location.

REST

To list the LROs in a Google Cloud project and location, call theprojects.locations.operations.list method.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: Your Google Cloud project ID.
  • LOCATION: thelocation where one or more LROs are running, for example:
    • us - United States
    • eu - European Union
  • FILTER: (Required) Query for LROs to return. Options:
    • TYPE: (Required) LRO type to list. Options:
      • BATCH_PROCESS_DOCUMENTS
      • CREATE_PROCESSOR_VERSION
      • DELETE_PROCESSOR
      • ENABLE_PROCESSOR
      • DISABLE_PROCESSOR
      • UPDATE_HUMAN_REVIEW_CONFIG
      • HUMAN_REVIEW_EVENT
      • CREATE_LABELER_POOL
      • UPDATE_LABELER_POOL
      • DELETE_LABELER_POOL
      • DEPLOY_PROCESSOR_VERSION
      • UNDEPLOY_PROCESSOR_VERSION
      • DELETE_PROCESSOR_VERSION
      • SET_DEFAULT_PROCESSOR_VERSION
      • EVALUATE_PROCESSOR_VERSION
      • EXPORT_PROCESSOR_VERSION
      • UPDATE_DATASET
      • IMPORT_DOCUMENTS
      • ANALYZE_HITL_DATA
      • BATCH_MOVE_DOCUMENTS
      • RESYNC_DATASET
      • BATCH_DELETE_DOCUMENTS
      • DELETE_DATA_LABELING_JOB
      • EXPORT_DOCUMENTS

HTTP method and URL:

GET https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations?filter=TYPE=TYPE

To send your request, choose one of these options:

curl

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login , or by usingCloud Shell, which automatically logs you into thegcloud CLI . You can check the currently active account by runninggcloud auth list.

Execute the following command:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations?filter=TYPE=TYPE"

PowerShell

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login . You can check the currently active account by runninggcloud auth list.

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations?filter=TYPE=TYPE" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{  "operations": [    {      "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",      "metadata": {        "@type": "type.googleapis.com/google.cloud.documentai.v1.BatchProcessMetadata",        "state": "SUCCEEDED",        "stateMessage": "Processed 1 document(s) successfully",        "createTime": "TIMESTAMP",        "updateTime": "TIMESTAMP",        "individualProcessStatuses": [          {            "inputGcsSource": "INPUT_BUCKET_FOLDER/DOCUMENT1.ext",            "status": {},            "outputGcsDestination": "OUTPUT_BUCKET_FOLDER/OPERATION_ID/0",            "humanReviewStatus": {              "state": "ERROR",              "stateMessage": "Sharded document protos are not supported for human review."            }          }        ]      },      "done": true,      "response": {        "@type": "type.googleapis.com/google.cloud.documentai.v1.BatchProcessResponse"      }    },    ...  ]}

Go

For more information, see theDocument AIGo API reference documentation.

To authenticate to Document AI, set up Application Default Credentials. For more information, seeSet up authentication for a local development environment.

packagemainimport("context"documentai"cloud.google.com/go/documentai/apiv1"longrunningpb"cloud.google.com/go/longrunning/autogen/longrunningpb""google.golang.org/api/iterator")funcmain(){ctx:=context.Background()// This snippet has been automatically generated and should be regarded as a code template only.// It will require modifications to work:// - It may require correct/in-range values for request initialization.// - It may require specifying regional endpoints when creating the service client as shown in://   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Optionsc,err:=documentai.NewDocumentProcessorClient(ctx)iferr!=nil{// TODO: Handle error.}deferc.Close()req:=&longrunningpb.ListOperationsRequest{// TODO: Fill request struct fields.// See https://pkg.go.dev/cloud.google.com/go/longrunning/autogen/longrunningpb#ListOperationsRequest.}it:=c.ListOperations(ctx,req)for{resp,err:=it.Next()iferr==iterator.Done{break}iferr!=nil{// TODO: Handle error.}// TODO: Use resp._=resp// If you need to access the underlying RPC response,// you can do so by casting the `Response` as below.// Otherwise, remove this line. Only populated after// first call to Next(). Not safe for concurrent access._=it.Response.(*longrunningpb.ListOperationsResponse)}}

Python

For more information, see theDocument AIPython API reference documentation.

To authenticate to Document AI, set up Application Default Credentials. For more information, seeSet up authentication for a local development environment.

fromgoogle.api_core.client_optionsimportClientOptionsfromgoogle.cloudimportdocumentai# type: ignorefromgoogle.longrunning.operations_pb2importListOperationsRequest# type: ignore# TODO(developer): Uncomment these variables before running the sample.# project_id = "YOUR_PROJECT_ID"# location = "YOUR_PROCESSOR_LOCATION"  # Format is "us" or "eu"# Create filter in https://google.aip.dev/160 syntax# For full options, refer to:# https://cloud.google.com/document-ai/docs/long-running-operations#listing_long-running_operations# operations_filter = 'YOUR_FILTER'# Example:# operations_filter = "TYPE=BATCH_PROCESS_DOCUMENTS AND STATE=RUNNING"deflist_operations_sample(project_id:str,location:str,operations_filter:str)->None:# You must set the `api_endpoint` if you use a location other than "us".opts=ClientOptions(api_endpoint=f"{location}-documentai.googleapis.com")client=documentai.DocumentProcessorServiceClient(client_options=opts)# Format: `projects/{project_id}/locations/{location}`name=client.common_location_path(project=project_id,location=location)request=ListOperationsRequest(name=f"{name}/operations",filter=operations_filter,)# Make ListOperations requestoperations=client.list_operations(request=request)# Print the Operation Informationprint(operations)

Polling a long-running operation

The following samples show how to poll the status of an LRO.

REST

To poll an LRO, repeatedly call theprojects.locations.operations.get method until the operation finishes. Use a backoff between each poll request, such as 10 seconds.

Before using any of the request data below, make the following replacements:

  • PROJECT_ID: your Google Cloud project ID
  • LOCATION: the location where the LRO is running
  • OPERATION_ID: the identifier for the LRO

HTTP method and URL:

GEThttps://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID

To send your request, choose one of these options:

Note: If you are not executing the commands below fromCloud Shell orCompute Engine, ensure you have set theGOOGLE_APPLICATION_CREDENTIALS environment variable to your service account private key file path.

curl

Execute the following command to poll for the status of an LRO every 10 seconds:

whiletrue;\docurl-XGET\-H"Authorization: Bearer "$(gcloudauthprint-access-token)\"https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID";\sleep10;\done

You should receive a JSON response every 10 seconds.While the operation is running, the response will contain"state": "RUNNING".When the operation finishes, the response will contain"state": "SUCCEEDED" and"done": true.

Response

{  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",  "metadata": {    "@type": "type.googleapis.com/google.cloud.documentai.v1.BatchProcessMetadata",    "state": "RUNNING",    "createTime": "TIMESTAMP",    "updateTime": "TIMESTAMP"  }}{  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",  "metadata": {    "@type": "type.googleapis.com/google.cloud.documentai.v1.BatchProcessMetadata",    "state": "RUNNING",    "createTime": "TIMESTAMP",    "updateTime": "TIMESTAMP"  }}...{  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",  "metadata": {    "@type": "type.googleapis.com/google.cloud.documentai.v1.BatchProcessMetadata",    "state": "SUCCEEDED",    "stateMessage": "Processed 1 document(s) successfully",    "createTime": "TIMESTAMP",    "updateTime": "TIMESTAMP",    "individualProcessStatuses": [      {        "inputGcsSource": "INPUT_BUCKET_FOLDER/DOCUMENT1.ext",        "status": {},        "outputGcsDestination": "OUTPUT_BUCKET_FOLDER/OPERATION_ID/0",        "humanReviewStatus": {          "state": "ERROR",          "stateMessage": "Sharded document protos are not supported for human review."        }      }    ]  },  "done": true,  "response": {    "@type": "type.googleapis.com/google.cloud.documentai.v1.BatchProcessResponse"  }}

PowerShell

Execute the following command to poll for the status of an LRO every ten seconds:

$cred=gcloudauthprint-access-token$headers=@{Authorization="Bearer$cred"}Do{Invoke-WebRequest`-MethodGet`-Headers$headers`-Uri"https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID"|Select-Object-ExpandContentsleep10}while($true)

You should receive a JSON response every 10 seconds.While the operation is running, the response will contain"state": "RUNNING".When the operation finishes, the response will contain"state": "SUCCEEDED" and"done": true.

Response

{  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",  "metadata": {    "@type": "type.googleapis.com/google.cloud.documentai.v1.BatchProcessMetadata",    "state": "RUNNING",    "createTime": "TIMESTAMP",    "updateTime": "TIMESTAMP"  }}{  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",  "metadata": {    "@type": "type.googleapis.com/google.cloud.documentai.v1.BatchProcessMetadata",    "state": "RUNNING",    "createTime": "TIMESTAMP",    "updateTime": "TIMESTAMP"  }}...{  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",  "metadata": {    "@type": "type.googleapis.com/google.cloud.documentai.v1.BatchProcessMetadata",    "state": "SUCCEEDED",    "stateMessage": "Processed 1 document(s) successfully",    "createTime": "TIMESTAMP",    "updateTime": "TIMESTAMP",    "individualProcessStatuses": [      {        "inputGcsSource": "INPUT_BUCKET_FOLDER/DOCUMENT1.ext",        "status": {},        "outputGcsDestination": "OUTPUT_BUCKET_FOLDER/OPERATION_ID/0",        "humanReviewStatus": {          "state": "ERROR",          "stateMessage": "Sharded document protos are not supported for human review."        }      }    ]  },  "done": true,  "response": {    "@type": "type.googleapis.com/google.cloud.documentai.v1.BatchProcessResponse"  }}

Python

For more information, see theDocument AIPython API reference documentation.

To authenticate to Document AI, set up Application Default Credentials. For more information, seeSet up authentication for a local development environment.

fromtimeimportsleepfromgoogle.api_core.client_optionsimportClientOptionsfromgoogle.cloudimportdocumentai# type: ignorefromgoogle.longrunning.operations_pb2importGetOperationRequest# type: ignore# TODO(developer): Uncomment these variables before running the sample.# location = "YOUR_PROCESSOR_LOCATION"  # Format is "us" or "eu"# operation_name = "YOUR_OPERATION_NAME"  # Format is "projects/{project_id}/locations/{location}/operations/{operation_id}"defpoll_operation_sample(location:str,operation_name:str)->None:# You must set the `api_endpoint` if you use a location other than "us".opts=ClientOptions(api_endpoint=f"{location}-documentai.googleapis.com")client=documentai.DocumentProcessorServiceClient(client_options=opts)request=GetOperationRequest(name=operation_name)whileTrue:# Make GetOperation requestoperation=client.get_operation(request=request)# Print the Operation Informationprint(operation)# Stop polling when Operation is no longer runningifoperation.done:break# Wait 10 seconds before polling againsleep(10)
Note: The code is a generic function designed for polling an LRO to check thestatus of single or multiple batch_process jobs. In cases where you want to waituntil thebatch_process_documents operation is completed fully, client librariesoffer their own polling methods. Refer toBatch processingfor more information.

Cancelling a long-running operation

The following samples show how to cancel an LRO while it is running.

REST

To cancel an LRO, call theprojects.locations.operations.cancel method.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: Your Google Cloud project ID.
  • LOCATION: thelocation where the LRO is running, for example:
    • us - United States
    • eu - European Union
  • OPERATION_ID: The ID of your operation. The ID is the last element of the nameof your operation. For example:
    • Operation name:projects/PROJECT_ID/locations/LOCATION/operations/bc4e1d412863e626
    • Operation id:bc4e1d412863e626

HTTP method and URL:

POST https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID:cancel

To send your request, choose one of these options:

curl

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login , or by usingCloud Shell, which automatically logs you into thegcloud CLI . You can check the currently active account by runninggcloud auth list.

Execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d "" \
     "https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID:cancel"

PowerShell

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login . You can check the currently active account by runninggcloud auth list.

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -Uri "https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID:cancel" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{}
If you attempt to cancel an operation that has already completed, you should receive the following error message:
"error":{"code":400,"message":"Operation has completed and cannot be cancelled: 'PROJECT_ID/locations/LOCATION/operations/OPERATION_ID'.","status":"FAILED_PRECONDITION"}

Go

For more information, see theDocument AIGo API reference documentation.

To authenticate to Document AI, set up Application Default Credentials. For more information, seeSet up authentication for a local development environment.

packagemainimport("context"documentai"cloud.google.com/go/documentai/apiv1"longrunningpb"cloud.google.com/go/longrunning/autogen/longrunningpb")funcmain(){ctx:=context.Background()// This snippet has been automatically generated and should be regarded as a code template only.// It will require modifications to work:// - It may require correct/in-range values for request initialization.// - It may require specifying regional endpoints when creating the service client as shown in://   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Optionsc,err:=documentai.NewDocumentProcessorClient(ctx)iferr!=nil{// TODO: Handle error.}deferc.Close()req:=&longrunningpb.CancelOperationRequest{// TODO: Fill request struct fields.// See https://pkg.go.dev/cloud.google.com/go/longrunning/autogen/longrunningpb#CancelOperationRequest.}err=c.CancelOperation(ctx,req)iferr!=nil{// TODO: Handle error.}}

Python

For more information, see theDocument AIPython API reference documentation.

To authenticate to Document AI, set up Application Default Credentials. For more information, seeSet up authentication for a local development environment.

fromgoogle.api_core.client_optionsimportClientOptionsfromgoogle.cloudimportdocumentai# type: ignorefromgoogle.longrunning.operations_pb2importCancelOperationRequest# type: ignore# TODO(developer): Uncomment these variables before running the sample.# location = "YOUR_PROCESSOR_LOCATION"  # Format is "us" or "eu"# operation_name = "YOUR_OPERATION_NAME"  # Format is "projects/{project_id}/locations/{location}/operations/{operation_id}"defcancel_operation_sample(location:str,operation_name:str)->None:# You must set the `api_endpoint` if you use a location other than "us".opts=ClientOptions(api_endpoint=f"{location}-documentai.googleapis.com")client=documentai.DocumentProcessorServiceClient(client_options=opts)request=CancelOperationRequest(name=operation_name)# Make CancelOperation requestclient.cancel_operation(request=request)print(f"Operation{operation_name} cancelled")

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.