> 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-assistant-turn/.

# Get an edit assistant turn

Reads one edit-assistant turn: `processing` while it runs, `complete` once `reply`, `proposals`, and `moments` are ready, or `failed` with `error`.

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

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

## Request

Pass `project_id`, `generation_id`, and `turn_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. |
| `turn_id` | string | Yes | Identifier of the assistant turn returned when the turn was created. |

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

turn = client.assistant.get_turn(
    "73118d99-36cf-4039-8005-b962d522fff7",
    "73c84c4a-c1ca-5485-b396-171ab632d4b7",
    "8f14e45fceea4e6b9d2c7a1b3e5d9f02",
)
```

**Node.js**

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

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

const turn =
  await client.assistant.getTurn(
    "73118d99-36cf-4039-8005-b962d522fff7",
    "73c84c4a-c1ca-5485-b396-171ab632d4b7",
    "8f14e45fceea4e6b9d2c7a1b3e5d9f02",
  )
```

**cURL**

```bash
curl "https://api.diffio.ai/v2/projects/73118d99-36cf-4039-8005-b962d522fff7/generations/73c84c4a-c1ca-5485-b396-171ab632d4b7/transcript/assistant/turns/8f14e45fceea4e6b9d2c7a1b3e5d9f02" \
  -H "Authorization: Bearer $DIFFIO_API_KEY"
```

## Response

Returns the `transcript_assistant_turn`, merged with answer fields once `status` is `complete`.

Success: `200`

### Response fields

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `object` | string | Always | Resource type, always `"transcript_assistant_turn"`. |
| `id` | string | Always | Unique identifier of the assistant turn. |
| `project_id` | string | Always | Identifier of the parent project. |
| `generation_id` | string | Always | Identifier of the Pro generation. |
| `status` | string | Always | Turn state: `processing` while running, `complete` when answer fields are populated, or `failed` when `error` is set. |
| `created_at` | string \| null | Always | ISO 8601 UTC timestamp when the turn was created, or `null`. |
| `completed_at` | string \| null | Always | ISO 8601 UTC timestamp when the turn finished, or `null` while `processing`. |
| `error` | object \| null | Always | Failure details when `status` is `failed`, or `null` otherwise. |
| `error.code` | string | Always | Stable `snake_case` turn failure code (`rate_limited`, `assistant_timeout`, `assistant_unavailable`, `not_editable`, `invalid_field`, `permission_denied`, `unauthenticated`, `project_not_found`, or `internal_error`). |
| `error.message` | string | Always | Human-readable message explaining why the turn failed. |
| `reply` | string | Sometimes | Assistant reply text to show the user (present when `status` is `complete`, up to 1,200 characters). |
| `proposals` | array | Sometimes | Proposed transcript edit groups referencing `words[].id` (present when `status` is `complete`). [Fields below](#fields-proposals) |
| `moments` | array | Sometimes | Notable timestamps referenced in the answer (up to 8 items, present when `status` is `complete`). [Fields below](#fields-moments) |
| `unclear_word_ids` | array | Sometimes | Word IDs that an audio listening pass found hard to understand. |
| `speaker_turns` | array | Sometimes | Detected speaker turn starts keyed by `word_id`. |
| `speaker_turns[].word_id` | string | Sometimes | First word ID of the speaker turn. |
| `speaker_turns[].speaker` | string | Sometimes | Speaker label for the turn. |
| `shortening` | object \| null | Sometimes | Suggested `tighten` settings for audio projects, or `null`. [Fields below](#fields-shortening) |
| `feedback_offer` | object \| null | Sometimes | Optional prompt inviting user feedback when the assistant detects a product report, or `null`; send the report with [Send assistant feedback](https://diffio.ai/docs/api-reference/create-transcript-assistant-feedback/). |
| `feedback_offer.kind` | string | Sometimes | Feedback category (`bug`, `feature`, or `other`). |
| `feedback_offer.summary` | string | Sometimes | Suggested one-line summary for the feedback report. |
| `notices` | array | Sometimes | Informational notices returned alongside the answer. |
| `windows_total` | integer | Sometimes | Total 30-second windows that the current draft plus all proposals would restore. |

**`proposals[]` fields**

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `proposals[].id` | string | Sometimes | Identifier of the proposal. |
| `proposals[].title` | string | Sometimes | Short title summarizing the proposed edits. |
| `proposals[].icon` | string | Sometimes | Category icon identifier for the proposal. Values: `filler`, `replace`, `rephrase`, `mute`, `regenerate`, `grammar`, `cleanup`, `insert`. |
| `proposals[].changes` | array | Sometimes | Ordered word-level changes in this proposal. |
| `proposals[].changes[].id` | string | Sometimes | Identifier of the change. |
| `proposals[].changes[].kind` | string | Sometimes | Change action: `replace`, `remove`, `insert`, or `regenerate`. |
| `proposals[].changes[].word_ids` | array | Sometimes | Ordered `words[].id` values covered by this change. |
| `proposals[].changes[].before` | string | Sometimes | Original words before the change. |
| `proposals[].changes[].after` | string | Sometimes | Words after the change, or `""` when removing words. |
| `proposals[].changes[].reason` | string | Sometimes | Short reason explaining the change. |
| `proposals[].changes[].start_seconds` | number \| null | Sometimes | Start timestamp in seconds on the recording, or `null`. |
| `proposals[].changes[].end_seconds` | number \| null | Sometimes | End timestamp in seconds on the recording, or `null`. |
| `proposals[].windows` | integer | Sometimes | Additional 30-second restore windows this proposal adds to an edit. |

**`moments[]` fields**

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `moments[].start_seconds` | number | Sometimes | Moment start time in seconds. |
| `moments[].end_seconds` | number \| null | Sometimes | Moment end time in seconds, or `null`. |
| `moments[].label` | string | Sometimes | Short label describing the moment. |
| `moments[].word_id` | string \| null | Sometimes | Associated `words[].id`, or `null`. |

**`shortening` fields**

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `shortening.close_removed_gaps` | boolean | Sometimes | Whether to close silence left by removed words. |
| `shortening.max_pause_seconds` | number \| null | Sometimes | Suggested maximum pause length in seconds, or `null`. |
| `shortening.estimated_seconds` | number | Sometimes | Estimated seconds saved by applying the shortening. |
| `shortening.reason` | string | Sometimes | Explanation for the shortening suggestion. |

## Example response (200)

**Successful response**

```json
{
  "object": "transcript_assistant_turn",
  "id": "8f14e45fceea4e6b9d2c7a1b3e5d9f02",
  "project_id": "73118d99-36cf-4039-8005-b962d522fff7",
  "generation_id": "73c84c4a-c1ca-5485-b396-171ab632d4b7",
  "status": "complete",
  "created_at": "2026-11-13T00:40:00.418207Z",
  "completed_at": "2026-11-13T00:40:06.902114Z",
  "error": null,
  "reply": "No filler words were found in this transcript.",
  "proposals": [],
  "moments": [],
  "unclear_word_ids": []
}
```

## Return codes

- `200`
  - Returns the assistant turn (`processing`
  - `complete`
  - `failed`)
- `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: [`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)
  - Turn not found: [`transcript_assistant_turn_not_found`](https://diffio.ai/docs/api-reference/errors/#transcript_assistant_turn_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

- A turn that listens to the audio can take up to a few minutes; any turn still `processing` after 600 seconds reports `status: "failed"` with `error.code: "assistant_timeout"`.
- There is no list-turns endpoint; keep `id` from [Ask the edit assistant](https://diffio.ai/docs/api-reference/create-transcript-assistant-turn/) or listen for `transcript_assistant_turn.completed` and `transcript_assistant_turn.failed` webhooks.

## Related pages

- Previous: [Ask the edit assistant](https://diffio.ai/docs/api-reference/create-transcript-assistant-turn/): Start an asynchronous edit-assistant chat turn on a finished Pro generation's transcript.
- Next: [Send assistant feedback](https://diffio.ai/docs/api-reference/create-transcript-assistant-feedback/): Send the Diffio team a bug report or an idea about the edit assistant, with the conversation if wanted.

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