Get run status
Poll a run for its state and collect its outputs.
On this page
Returns the current state of a run, and its outputs once it succeeds. Prefer a webhook in production and use this to poll when you cannot receive one.
https://api2.rundiffusion.com/api/v2/generate/{request_id}Request
Headers
AuthorizationstringRequired- Bearer token. This endpoint accepts an OAuth device flow token, a Personal API Access Token, or a Company API Access Token. See Authentication.
Authorization: Bearer eyJhbGciOi…
Path
request_idstringRequired- The request_id from the create response. Prefer following status_url, which already has it filled in.
https://api2.rundiffusion.com/api/v2/generate/9f8e7d6c-…
No query parameters and no body.
Response
{
"request_id": "9f8e7d6c-…",
"status": "succeeded",
"created": "2026-05-04T10:00:00Z",
"queued_at": "2026-05-04T10:00:01Z",
"completed_at": "2026-05-04T10:00:09Z",
"retry_after_seconds": null,
"outputs": [
{
"type": "IMG",
"url": "https://rundiffusion.com/...",
"mime_type": "image/jpeg",
"width": 1024,
"height": 1024,
"duration_seconds": null,
"size_bytes": 244000,
"expires_at": "2026-05-18T10:00:09Z",
"expired": false
}
],
"metadata": { "trace_id": "client-trace-1" },
"error": null,
"tokens_charged": 85,
"tokens_returned": 0
}A terminal failure returns 200 too, with the reason in error and the hold
refunded when the failure was not the caller's fault:
{
"request_id": "9f8e7d6c-…",
"status": "failed",
"created": "2026-05-04T10:00:00Z",
"queued_at": "2026-05-04T10:00:01Z",
"completed_at": "2026-05-04T10:00:04Z",
"retry_after_seconds": null,
"outputs": [],
"metadata": {},
"error": {
"code": "CONTENT_POLICY_VIOLATION",
"message": "Provider or NSFW filter flagged the result.",
"retryable": false
},
"tokens_charged": 85,
"tokens_returned": 85
}status is one of:
| Status | Meaning |
|---|---|
pending | Accepted and queued. |
processing | Running now. |
succeeded | Finished. outputs holds the results. |
failed | Terminal failure. error holds the envelope. |
Only succeeded and failed are terminal. While the run is in flight,
retry_after_seconds tells you how long to wait before polling again; it is
null once the run is terminal.
Output fields
Output URLs are signed and expiring, and a run's objects live for about
14 days from creation. Every status fetch inside that window mints a fresh
signed URL, so re-fetch rather than storing one. Once expires_at passes, the
same endpoint returns expired: true and url: null and the bytes are gone, so
download anything you need to keep.
Each entry in outputs
typestring- Output kind: IMG, VID, ASSET_3D, LAYERS.
urlstring | null- Signed download URL. Null when the output has no stored object or has expired.
mime_typestring | null- MIME type of the output.
widthinteger | null- Pixel width, for visual output.
heightinteger | null- Pixel height, for visual output.
duration_secondsnumber | null- Duration, for video or audio output.
size_bytesinteger | null- Size of the output file in bytes.
expires_atstring (ISO 8601) | null- When the signed URL stops working.
expiredboolean- Whether the URL has already expired.
tokens_charged is what the run actually cost, and tokens_returned is any
refund for results that failed to produce.
Errors
| Code | What to do |
|---|---|
REQUEST_NOT_FOUND | Returns 404. No such request_id, or not one this credential can see. A run belonging to somebody else reads the same as one that never existed. |
RATE_LIMITED | Returns 429. See Rate limits. See Rate limits. |
The full list is in Errors.