Problem
Some actions take seconds or hours: generating a report, processing a refund, provisioning infrastructure. Agents see a spinner, or nothing, and cannot tell whether to wait, retry, or give up.
Context
Use this pattern when:
- The action completes asynchronously.
- The agent may need to report progress to a person or continue other work meanwhile.
Recommended solution
Respond to long-running actions with 202 Accepted and a status resource URL. The status resource reports the state (queued, running, succeeded, failed), progress where measurable, an estimated completion time, and the final result or error.
- 01Return 202 with a Location header pointing to the status resource.
- 02Report state, progress, and estimated completion.
- 03Include the result or error when finished.
- 04Offer webhooks or server-sent events for agents that can receive them.
Interaction diagram
Example implementation
Illustrative exampleExamples use a fictional store and illustrative field names. Adapt the shape to your stack; the qualities matter more than the exact format.
{
"id": "job_55",
"action": "export_report",
"state": "running",
"progress": { "completed": 6, "total": 10, "unit": "sections" },
"estimatedCompletion": "2026-10-06T14:05:30Z",
"pollAfterSeconds": 5
}Accessibility and security
Accessibility
- Expose progress to people with the same data, using live regions for status updates.
Security
- Status resources should be readable only by the grant that started the job.
Related patterns
Applies the principles Transparent State and Verifiable Outcomes.