Long-Running Operations (202 + Status Resources) — REST APIs in Depth

Don't hold HTTP connections open for slow work. Return 202 Accepted with a Location header pointing to an operation/job resource that clients poll (honoring Retry-After) or subscribe to via webhooks/SSE. The operation resource reports status (queued, running, succeeded, failed), progress and, on completion, the result or a link to it. Make creation idempotent and support cancellation (POST /operations/{id}:cancel).

How clients learn the result

Criterion	Polling	Webhook callback	SSE / WebSocket
Client complexity	Low	Needs public endpoint	Persistent connection
Latency to result	Poll interval	Immediate	Immediate
Works for servers & browsers	Yes	Servers only	Mostly browsers/apps
Reliability	Simple; idempotent GETs	Needs retries + signatures	Needs reconnects

POST /reports
Idempotency-Key: 0c1e…
{"type": "sales", "period": "2026-Q3"}

HTTP/1.1 202 Accepted
Location: /operations/op_77
Retry-After: 5

GET /operations/op_77
{"id": "op_77", "status": "running", "progress": 42, "created_at": "2026-10-10T09:00:00Z"}

GET /operations/op_77
{"id": "op_77", "status": "succeeded", "result": {"report_url": "/reports/rep_9"}}

Common pitfalls

Synchronous requests that exceed gateway timeouts (often 30–60 s).
No way to cancel or inspect failed jobs.
Polling without Retry-After guidance.

Key points

202 + operation resource
Poll, webhook or stream
Idempotent creation, cancellable jobs

Further reading: Google AIP-151: Long-running operations

Practice questions

Why return a separate operation resource instead of the final resource?

Answer

The final resource may not exist until the work finishes, and the operation captures status, progress, errors and cancellation independently of the result.

How do you prevent duplicate jobs when a client retries the POST?

Answer

Require an Idempotency-Key; on retry return the same 202 and operation id instead of starting a new job.