Long-Running Operations and Bulk Requests

Do not make clients wait on a socket

When work takes more than a few seconds (video processing, large exports, report generation), accept the request, respond 202 Accepted with a Location pointing to a status resource (/exports/exp_9), and let the client poll it (pending, running, succeeded with a result link, or failed with a problem) or receive a webhook on completion. Include a Retry-After hint for polling. For bulk operations (create 500 items), decide the semantics up front: all-or-nothing, or per-item results (a 207-style list of successes and failures), cap the batch size, and make each item idempotent. Bulk endpoints reduce round trips but add complexity, so offer them only where clients truly need them.

The 202 flow

Illustrative HTTP exchange; the demo API does not implement exports.

POST /v1/exports          {"report": "orders", "month": "2026-09"}
<- 202 Accepted
   Location: /v1/exports/exp_9
   Retry-After: 5

GET /v1/exports/exp_9
<- 200 {"id":"exp_9","status":"running","progress":0.4}

GET /v1/exports/exp_9      (later)
<- 200 {"id":"exp_9","status":"succeeded","download_url":"https://files.example.com/exp_9.csv"}

Quick check: What should an API return for a request that will take minutes to finish?

• 200 after blocking for minutes
• 202 Accepted with a Location for a status resource
• 204 and forget it
• 401