> For the complete documentation index, see [llms.txt](https://diffio.ai/llms.txt). This page is also available as HTML at https://diffio.ai/docs/api-reference/get-generation/.

# Get a generation

Returns one generation, including its `status`, live `stage` and `stage_progress`, worker `queue` details, `files_available`, `stems_status`, `transcription_status`, and `error` when failed.

GET `https://api.diffio.ai/v2/projects/{project_id}/generations/{generation_id}`

- Key scope: `generations:read`
- Auth header: `Authorization: Bearer <apiKey>`
- Body: None

Overall `status`

1. queued
2. processing
3. complete
4. *or* failed

`stage` while it runs

1. pending
2. preparing
3. transcribing
4. queued
5. starting
6. downloading
7. decoding
8. restoring
9. finalizing
10. uploading
11. complete
12. *or* failed

`stage_progress` in the example response

`overall_percent`

88%

`available_through_seconds`

0 of 31.8 s

**Poll until `status` is `complete` or `failed`.**

## Request

Pass `project_id` and `generation_id` in the path; takes no request body.

### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `project_id` | string | Yes | Unique identifier of the project. |
| `generation_id` | string | Yes | Unique identifier of the generation within the project. |

### Headers

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `Diffio-End-User` | string | No | Optional end-user identifier (up to 128 characters). Scopes the request to that end user's projects; omit to act across the whole account. |

## Example request

**Python**

```python
import os
from diffio import DiffioClient

key = os.environ["DIFFIO_API_KEY"]
client = DiffioClient(api_key=key)

generation = client.generations.get(
    "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
    "ce832a32-a1ce-516a-b8bd-75457bd8517f",
)
```

**Node.js**

```javascript
import { DiffioClient } from "diffio"

const client = new DiffioClient({
  apiKey: process.env.DIFFIO_API_KEY,
})

const generation =
  await client.generations.get(
    "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
    "ce832a32-a1ce-516a-b8bd-75457bd8517f",
  )
```

**cURL**

```bash
curl "https://api.diffio.ai/v2/projects/62f62565-049f-5e7e-bbd2-9de0cf7ddbfe/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f" \
  -H "Authorization: Bearer $DIFFIO_API_KEY"
```

## Response

Returns the `generation` object.

Success: `200`

### Response fields

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | Always | Unique generation identifier (UUID). |
| `object` | string | Always | Resource type, always `"generation"`. |
| `status` | string | Always | Lifecycle state: `queued`, `processing`, `complete`, or `failed`. |
| `model` | string \| null | Always | Hosted model that ran or is running (such as `diffio-4.7-flash` or `diffio-4.7-pro`), or `null`. |
| `stage` | string \| null | Always | Current worker stage (`pending`, `preparing`, `transcribing`, `queued`, `starting`, `downloading`, `decoding`, `restoring`, `finalizing`, `uploading`, then `complete` or `failed`), or `null`. |
| `stage_progress` | object \| null | Always | Live worker progress while `status` is `processing`, or `null` before a worker reports progress and after completion. [Fields below](#fields-stage-progress) |
| `queue` | object \| null | Always | Worker queue snapshot while the generation waits to start, or `null` otherwise. [Fields below](#fields-queue) |
| `error` | object \| null | Always | Failure details when `status` is `failed` (also includes boolean `retryable` and nullable `explanation` on the wire), or `null` otherwise. |
| `error.code` | string | Always | Stable `snake_case` generation failure code (such as `restoration_failed`, `no_speech_detected`, `transcription_failed`, `upload_missing`, or `generation_failed`). |
| `error.message` | string | Always | Human-readable message explaining why the generation failed. |

**`stage_progress` fields**

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `stage_progress.overall_percent` | number | Sometimes | Overall generation completion percentage from `0` to `100`, present once reported. |
| `stage_progress.stage_percent` | number | Sometimes | Completion percentage of the current `stage` from `0` to `100`, present once reported. |
| `stage_progress.bytes_done` | number | Sometimes | Bytes transferred so far in a `downloading` or `uploading` stage. |
| `stage_progress.bytes_total` | number | Sometimes | Total bytes to transfer in the current `downloading` or `uploading` stage. |
| `stage_progress.available_through_seconds` | number | Sometimes | Seconds of restored output already playable via `hls_master` while processing. |
| `stage_progress.duration_seconds` | number | Sometimes | Recording length in seconds as reported by the worker. |

**`queue` fields**

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `queue.position` | integer \| null | Always | Number of queued jobs ahead of this generation, or `null`. |
| `queue.connected_workers` | integer \| null | Always | Total workers connected to the queue, or `null`. |
| `queue.idle_workers` | integer \| null | Always | Connected workers currently idle, or `null`. |
| `queue.busy_workers` | integer \| null | Always | Connected workers currently running jobs, or `null`. |
| `queue.wait_reason` | string \| null | Always | Why the job is waiting (`all_busy`, `no_workers`, or `next_in_line`), or `null`. |
| `queue.message` | string | Always | Human-readable message explaining why the generation is waiting. |

**Other response fields**

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `project_id` | string | Always | Identifier of the parent project. |
| `requested_model` | string \| null | Always | Model name sent in the request (hosted model, tier alias, or retired model), or `null`. |
| `substituted` | boolean | Always | True when `requested_model` was a retired model name and ran on the current hosted model of the same tier; `false` for hosted names and aliases. |
| `price_per_hour_usd` | number \| null | Always | List price per hour in USD applied to this generation (for retired models, the lower of the requested and serving models' list prices), or `null`. |
| `warnings` | array | Always | Non-fatal warnings recorded during processing (the generation still runs). [Fields below](#fields-warnings) |
| `label` | string \| null | Always | Caller-supplied label (up to 120 characters), `Transcript edit` for an edit, or `null` when none was set. |
| `kind` | string | Always | Generation kind: `restore` for a full recording restore, or `edit` for a transcript edit of a finished Pro generation. |
| `source_generation_id` | string \| null | Always | For `kind: "edit"`, the Pro generation that was edited; `null` for `restore`. |
| `edit` | object \| null | Always | Transcript edit details and progress when `kind` is `edit`, or `null` for `restore`. [Fields below](#fields-edit) |
| `transcript_editable` | boolean | Always | True when this result's transcript can be edited via `POST .../edits` (a finished Pro result with stored edit latents). |
| `duration_seconds` | number \| null | Always | Duration of the restored output in seconds once known, or `null`. |
| `quality_score` | number \| null | Always | Estimated speech quality score of the result from `1` to `5`, or `null`. |
| `transcription_status` | string \| null | Always | Word-timed transcript status: `preparing`, `ready`, or `failed`; `null` when no transcription is reported. |
| `files_available` | array | Always | Sorted names of artifacts currently available from `GET .../media` (such as `audio`, `video`, `hls_master`, `transcript`, `stems_manifest`). |
| `stems_status` | string \| null | Always | Separated speech and background track status: `preparing`, `ready`, or `failed`; `null` when none are reported. |
| `created_at` | string \| null | Always | ISO 8601 UTC timestamp when the generation was created, or `null`. |
| `updated_at` | string \| null | Always | ISO 8601 UTC timestamp when the generation last changed, or `null`. |

**`warnings[]` fields**

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `warnings[].code` | string | Always | Warning code; `unsupported_language` when the transcript contains words in languages the model cannot restore. |
| `warnings[].languages` | array | Sometimes | ISO 639-1 language codes of unsupported words, ordered by word count. |
| `warnings[].message` | string | Always | Human-readable warning message. |

**`edit` fields**

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `edit.edit_count` | integer \| null | Always | Number of edits (each run of changed, inserted, or removed words between kept words counts once), or `null`. |
| `edit.max_windows` | integer \| null | Always | Maximum number of 30-second windows this edit could restore, or `null`. |
| `edit.windows` | integer \| null | Always | Actual number of windows restored (or being restored) by the worker, or `null` before starting. |
| `edit.windows_done` | integer \| null | Always | Number of restore windows completed so far, or `null`. |
| `edit.ranges` | array | Always | Time ranges on the recording (in seconds) covered by the restored windows. |
| `edit.ranges[].start` | number | Sometimes | Window start time in seconds. |
| `edit.ranges[].end` | number | Sometimes | Window end time in seconds. |
| `edit.billable_seconds` | integer \| null | Always | Seconds billed once complete (`30` per restored window, `0` when no window was restored), or `null` until complete. |
| `edit.cut_seconds` | number \| null | Always | Seconds trimmed from the recording by `tighten`, or `null`. |
| `edit.request_id` | string \| null | Always | Caller-supplied `request_id` from the edit request, or `null`. |
| `edit.language` | string \| null | Always | Primary language code used for the edit, or `null`. |
| `edit.tighten` | object \| null | Always | Silence-shortening settings applied by the edit, or `null` when none were requested. |
| `edit.tighten.close_removed_gaps` | boolean | Always | Whether silence left by removed words was closed. |
| `edit.tighten.max_pause_seconds` | number \| null | Always | Maximum pause duration in seconds after shortening, or `null` when pauses were left unchanged. |

## Example response (200)

**Response, key fields: Response: key fields**

```json
{
  "id": "ce832a32-a1ce-516a-b8bd-75457bd8517f",
  "object": "generation",
  "status": "processing",
  "stage": "finalizing",
  "stage_progress": {
    "overall_percent": 88,
    "stage_percent": 0,
    "available_through_seconds": 0,
    "duration_seconds": 31.8
  },
  "queue": null,
  "error": null,
  "model": "diffio-4.7-flash"
}
```

**Full response: Successful response**

```json
{
  "id": "ce832a32-a1ce-516a-b8bd-75457bd8517f",
  "object": "generation",
  "project_id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
  "status": "processing",
  "stage": "finalizing",
  "stage_progress": {
    "overall_percent": 88,
    "stage_percent": 0,
    "available_through_seconds": 0,
    "duration_seconds": 31.8
  },
  "queue": null,
  "warnings": [],
  "label": "Take 1",
  "kind": "restore",
  "source_generation_id": null,
  "edit": null,
  "transcript_editable": false,
  "duration_seconds": null,
  "quality_score": null,
  "transcription_status": "ready",
  "files_available": [],
  "error": null,
  "model": "diffio-4.7-flash",
  "requested_model": "diffio-flash",
  "substituted": false,
  "price_per_hour_usd": 5,
  "stems_status": null,
  "created_at": "2026-11-13T00:33:27.117344Z",
  "updated_at": "2026-11-13T00:33:36.673000Z"
}
```

## Return codes

- `200` Returns the requested generation.
- `400` `Diffio-End-User` exceeds 128 characters. [`invalid_header`](https://diffio.ai/docs/api-reference/errors/#invalid_header)
- `403` Key is inactive or lacks `generations:read`. [`permission_denied`](https://diffio.ai/docs/api-reference/errors/#permission_denied)
- `404` Project not found, or no generation with `generation_id` belongs to this project. [`project_not_found`](https://diffio.ai/docs/api-reference/errors/#project_not_found) [`generation_not_found`](https://diffio.ai/docs/api-reference/errors/#generation_not_found)
- **`401` `405` Same on every endpoint**

  - `401` Missing API key (code missing_api_key), or invalid API key (code invalid_api_key).
  - `405` HTTP method not supported on this path; check the Allow header (code method_not_allowed).

### Example error response

Errors are JSON: an `error` object with `code`, `message` and `request_id`. An unrecognized key returns `401`:

**Error response**

```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key.",
    "request_id": "dead773b60e148fd9e22d680a22fa701"
  }
}
```

## Notes

- Poll every couple of seconds until `status` is `complete` or `failed` (the SDKs' `generations.wait(...)` helper does this with a 2-second default interval), or subscribe to `generation.completed` and `generation.failed` webhooks.
- Separated speech and background tracks can finish after `status` reaches `complete`; wait for `stems_status: "ready"` (or the `generation.stems_ready` webhook) before calling mix or export routes.
- `hls_master` appears in `files_available` while the generation is still `processing` and can be streamed progressively via [Get a playback grant](https://diffio.ai/docs/api-reference/get-generation-media/).

## Related pages

- Previous: [List a project's generations](https://diffio.ai/docs/api-reference/list-project-generations/): List every restore and transcript edit generation on a project, newest first.
- Next: [Get a playback grant](https://diffio.ai/docs/api-reference/get-generation-media/): Mint 6-hour signed playback and download URLs for a generation's audio, video, HLS, stems, and transcript files.

- [Models](https://diffio.ai/docs/overview/models/): Choosing between Diffio 4.7 Flash and Pro.
- [API model cards](https://diffio.ai/api-model-cards/): Best uses for each model id.
- [API pricing](https://diffio.ai/api-pricing/): The current rate per hour for each model.
- [Webhooks guide](https://diffio.ai/docs/developers/webhooks/): Get notified when a generation finishes instead of polling.
