How do you design a status API for long-running generation?

How do you design a status API for long-running generation?

A status API lets the interface reconnect to work that continues independently. It should describe the application’s job state consistently across reloads and devices.

Return useful state

Include the job identifier, stage or status, relevant timestamps, and a result reference only when available. Distinguish waiting, processing, failure, and completion. If progress cannot be measured accurately, return a truthful stage instead of an invented percentage.

Control polling and visibility

Define how often the client checks, when it stops, and what it does on temporary network failure. Enforce ownership on every lookup. Avoid leaking private provider payloads in status responses. Test reloading during generation and returning after completion. A status request failure should not automatically change the actual job to failed; it may only mean the browser could not retrieve the current state.