> 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-transcript/.

# Get a generation's transcript

Returns a generation's word-timed transcript in a normalized `TranscriptWord` shape, ready to display or pass back to [Edit a generation's transcript](https://diffio.ai/docs/api-reference/create-transcript-edit/) and [Ask the edit assistant](https://diffio.ai/docs/api-reference/create-transcript-assistant-turn/).

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

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

## Request

Pass `project_id` and `generation_id` in the path, and optional `preview_seconds` in the query string.

### 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. |

### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `preview_seconds` | integer | No | Optional limit in seconds, from `4` to `3600` (rounded up to whole 4-second segments). Keeps only words starting within the preview. |

### 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)

transcript = client.transcripts.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 transcript =
  await client.transcripts.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/transcript" \
  -H "Authorization: Bearer $DIFFIO_API_KEY"
```

## Response

Returns the normalized `transcript` with full `text` and ordered `words`.

Success: `200`

### Response fields

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `object` | string | Always | Resource type, always `"transcript"`. |
| `generation_id` | string | Always | Identifier of the generation. |
| `text` | string | Always | Full transcript text (or the preview's words joined by spaces when `preview_seconds` is set). |
| `words` | array | Always | Ordered array of word-timed `TranscriptWord` objects. [Fields below](#fields-words) |
| `truncated` | boolean | Always | True when words starting at or after `preview_seconds` were omitted. |

**`words[]` fields**

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `words[].id` | string | Always | Stable word identifier within the transcript (stored ID or `word-{index}`). |
| `words[].text` | string | Always | Transcribed word text. |
| `words[].start` | number \| null | Always | Word start timestamp in seconds on the recording, or `null` when untimed. |
| `words[].end` | number \| null | Always | Word end timestamp in seconds on the recording, or `null` when untimed. |
| `words[].probability` | number \| null | Always | Transcriber confidence from `0` to `1`, or `null` when unknown. |
| `words[].speaker` | string | Sometimes | Speaker label when recorded by the transcriber (omitted on `preview_seconds` reads). |
| `words[].language` | string | Sometimes | Word language code when recorded by the transcriber. |

**Other response fields**

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `project_id` | string | Always | Identifier of the parent project. |
| `preview_seconds` | integer \| null | Always | Effective preview limit in seconds (rounded up to a multiple of `4`), or `null` for the complete transcript. |

## Example response (200)

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

```json
{
  "object": "transcript",
  "generation_id": "ce832a32-a1ce-516a-b8bd-75457bd8517f",
  "text": "For the lives of women have been more affected by its new horizons than those of any other group. Profound and stirring as have been accomplishments in the remoter fields of pure research, it is in the home that the applications of scientific achievement have perhaps been most far-reaching, and it is through changing conditions there that women have become the greatest beneficiaries in the modern scheme. Science has released them from much",
  "words": [
    {
      "id": "word-0",
      "text": "For",
      "start": 0.6,
      "end": 0.8,
      "probability": null,
      "language": "en",
      "label": "speech"
    },
    {
      "id": "word-1",
      "text": "the",
      "start": 0.84,
      "end": 0.94,
      "probability": null,
      "language": "en",
      "label": "speech"
    },
    {
      "id": "word-2",
      "text": "lives",
      "start": 1.04,
      "end": 1.32,
      "probability": null,
      "language": "en",
      "label": "speech"
    }
  ],
  "truncated": false
}
```

**Full response: Successful response**

```json
{
  "object": "transcript",
  "project_id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
  "generation_id": "ce832a32-a1ce-516a-b8bd-75457bd8517f",
  "text": "For the lives of women have been more affected by its new horizons than those of any other group. Profound and stirring as have been accomplishments in the remoter fields of pure research, it is in the home that the applications of scientific achievement have perhaps been most far-reaching, and it is through changing conditions there that women have become the greatest beneficiaries in the modern scheme. Science has released them from much",
  "words": [
    {
      "id": "word-0",
      "text": "For",
      "start": 0.6,
      "end": 0.8,
      "probability": null,
      "language": "en",
      "label": "speech"
    },
    {
      "id": "word-1",
      "text": "the",
      "start": 0.84,
      "end": 0.94,
      "probability": null,
      "language": "en",
      "label": "speech"
    },
    {
      "id": "word-2",
      "text": "lives",
      "start": 1.04,
      "end": 1.32,
      "probability": null,
      "language": "en",
      "label": "speech"
    }
  ],
  "preview_seconds": null,
  "truncated": false
}
```

## Return codes

- `200` Returns the normalized word-timed transcript.
- `400` `preview_seconds` is outside `4` to `3600`, or `Diffio-End-User` exceeds 128 characters. [`invalid_parameter`](https://diffio.ai/docs/api-reference/errors/#invalid_parameter) [`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: [`project_not_found`](https://diffio.ai/docs/api-reference/errors/#project_not_found)
  - Generation not found: [`generation_not_found`](https://diffio.ai/docs/api-reference/errors/#generation_not_found)
  - Finished generation has no stored transcript: [`transcript_not_found`](https://diffio.ai/docs/api-reference/errors/#transcript_not_found)
- `409` `transcription_status` is still `preparing` or the generation is running, or transcription failed; `details.transcription_status` reports the state. [`not_ready`](https://diffio.ai/docs/api-reference/errors/#not_ready) [`not_available`](https://diffio.ai/docs/api-reference/errors/#not_available)
- `422` Stored transcript file could not be parsed. [`transcript_unreadable`](https://diffio.ai/docs/api-reference/errors/#transcript_unreadable)
- **`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

- Both Flash and Pro restores produce a word-timed transcript (`transcription_status: "ready"`), while only Pro restores support [Edit a generation's transcript](https://diffio.ai/docs/api-reference/create-transcript-edit/).
- Pass the `words` array directly to `POST .../edits`, `POST .../edits/estimate`, or `POST .../transcript/assistant/turns` with your word-level edits applied.

## Related pages

- Previous: [Get an export](https://diffio.ai/docs/api-reference/get-generation-export/): Poll an export's render status and mint a fresh 6-hour download or playback URL once ready.
- Next: [Get the transcript draft](https://diffio.ai/docs/api-reference/get-transcript-draft/): Read the saved JSON editor draft and compare-and-swap revision for a generation's transcript.

- [Full API guide](https://diffio.ai/docs/developers/full-api-guide/): Every topic, limit and concept in one index.
- [Billing](https://diffio.ai/docs/overview/administration/billing/): Starter credit, metering and invoices.
