# API Async Long Running Operations

> Design async long-running REST operations with 202 Accepted, job resources, polling, Prefer respond-async, and webhook completion. Use when work exceeds request timeouts (reports, imports, provisioning) rather than streaming.

- Skill: `deangrant/api-async-long-running-operations` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add deangrant/api-async-long-running-operations`
- Raw SKILL.md: https://api.skillmd.com/api/skills/deangrant/api-async-long-running-operations/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: deangrant (https://skillmd.com/u/deangrant)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/deangrant/api-async-long-running-operations

---


# Asynchronous Long-Running Operations

Use this skill when work exceeds a single request/response cycle. Do **not**
hold connections open — acknowledge with **202**, run in background, expose a
**job** resource. Continuous push feeds belong in the streaming skill.

---

## 1. 202 Accepted

```http
HTTP/1.1 202 Accepted
Location: /jobs/8f3a
Retry-After: 5
```

202 means accepted/queued — **not** underlying success.

---

## 2. Job resource

First-class resource with `id`, `status`, `progress`, timestamps.

Status enum: `queued` → `running` → terminal `succeeded` | `failed` | `cancelled`.

On success: `result.href` or `303` to the final resource — do not inline huge
payloads. On failure: error in job body; poll still returns **200**.

---

## 3. Polling and notifications

Honor `Retry-After`; use ETag/`If-None-Match` for cheap unchanged polls. Prefer
**webhooks + polling fallback**. Sign webhook deliveries.

Optional: `Prefer: respond-async, wait=N` (RFC 7240) — sync if fast enough,
else 202. Protect creates with `Idempotency-Key`.

---

## 4. Quick checklist

- [ ] Clear criteria for async vs sync.
- [ ] 202 + `Location` + optional `Retry-After`.
- [ ] Documented status enum.
- [ ] Cheap polling; result via link/redirect.
- [ ] Webhooks + poll fallback.
- [ ] Idempotent job creation.

See [reference.md](reference.md) and [examples.md](examples.md).