# Generations

> Start and track Raywake generations. Learn job statuses, safe polling, idempotent retries, stored outputs and signed download links.

Canonical: https://raywake.si/docs/generations
Last updated: 2026-11-08

Generations run asynchronously. Start one, then poll the job until it reaches a terminal status.

## Statuses

**Generation statuses**

| Name | Type | Description |
| --- | --- | --- |
| `queued` | running | Accepted and waiting to start. Funds are held. |
| `submitting` | running | Being handed to the model. Funds are held. |
| `submitted` | running | The model is working. Funds are held. |
| `finalizing` | running | The result is ready and being saved to storage. Funds are captured; outputs appear in a few seconds. |
| `succeeded` | terminal | Outputs are available. Funds were captured. |
| `failed` | terminal | No result. Funds were released. |
| `submission_unknown` | held | Delivery could not be confirmed. Funds stay held until reconciled; this is not a refund. It can still turn succeeded or failed, so check again later (every few minutes). |
| `needs_review` | held | A result arrived but could not be read. Funds stay held until reviewed; the job then turns succeeded or failed. |
| `needs_reconciliation` | held | The job passed its settlement deadline. Funds stay held until reconciled; a late result can still turn it succeeded. |

## Polling

Poll `GET /v1/jobs/{job_id}` every 2–5 seconds. For short jobs you can instead pass `?wait=true` to `POST /v1/generate`; the request then returns when the job is terminal or after about three minutes, whichever comes first.

## Idempotency

Every generation requires an `Idempotency-Key` header. Retrying with the same key and the same body returns the original job instead of charging twice; the same key with a different body returns `409`. Use a fresh UUID per intended generation.

## How long are Raywake outputs and download links available?

Output files are stored for 30 days. Download URLs are signed for 7 days. While the file is still stored, request `GET /v1/jobs/{job_id}` again to obtain a fresh output link. Refreshing a link does not restart the file’s 30-day retention period. Download files you need to keep before they are deleted.

Use [GET /v1/storage?kind=output](https://raywake.si/docs/reference/storage) to list stored output files; expires_at records each file’s deletion time. Both retrieval routes require jobs:read and return only files or jobs belonging to your account.

[Inputs and files](https://raywake.si/docs/inputs)

## Related

- [API documentation](https://raywake.si/docs)
