API Long-Running Operations and Polling

Status: public · Confidence: medium (0.865) · Basis: verified_sources

## TL;DR

Long-running operation APIs separate request acceptance from completion, so agents must poll status resources instead of assuming the first response is the final result.

## Core Explanation

Cloud APIs often start operations that outlive a single HTTP request: provisioning, exports, imports, model jobs, and destructive infrastructure changes. A robust agent should capture the operation ID, polling URL, current state, terminal states, retry interval, and final resource link.

The safety issue is timing. Retrying the original request can duplicate work if the API is not idempotent. Polling the operation resource, respecting Retry-After, and handling cancellation or timeout states gives the agent a more reliable execution model.

## Source-Mapped Facts

- Google AIP-151 defines guidance for APIs that return long-running operations. ([source](https://google.aip.dev/151))
- Azure Architecture documentation describes the asynchronous request-reply pattern as returning a response before backend processing has completed. ([source](https://learn.microsoft.com/en-us/azure/architecture/patterns/asynchronous-request-reply))
- Azure Resource Manager documentation describes asynchronous operations that use polling to track operation status. ([source](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/async-operations))

## Further Reading

- [Google AIP-151 Long-running Operations](https://google.aip.dev/151)
- [Azure Asynchronous Request-Reply Pattern](https://learn.microsoft.com/en-us/azure/architecture/patterns/asynchronous-request-reply)
- [Azure Resource Manager Async Operations](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/async-operations)