Skip to content

For AI agents: every API docs page in one plain-text file is at /docs/llms-full.txt, and the documentation index is at /llms.txt. This page is available as Markdown at https://diffio.ai/docs/api-reference/get-transcript-assistant-turn.md, and every docs URL returns Markdown when requested with Accept: text/markdown.

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

FieldTypeRequiredDescription
#project_idstringRequired: YesUnique identifier of the project.
#generation_idstringRequired: YesUnique identifier of the generation within the project.
#turn_idstringRequired: YesIdentifier of the assistant turn returned when the turn was created.

Headers

FieldTypeRequiredDescription
#Diffio-End-UserstringRequired: NoOptional end-user identifier (up to 128 characters). Scopes the request to that end user's projects; omit to act across the whole account.

Request

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",
)

Response

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

Success: 200OK.

Response fields

FieldTypePresentDescription
#objectstringAlwaysResource type, always "transcript_assistant_turn".transcript_assistant_turn
#idstringAlwaysUnique identifier of the assistant turn.
#project_idstringAlwaysIdentifier of the parent project.
#generation_idstringAlwaysIdentifier of the Pro generation.
#statusstringAlwaysTurn state: processing while running, complete when answer fields are populated, or failed when error is set.processingcompletefailed
#created_atstring | nullAlwaysISO 8601 UTC timestamp when the turn was created, or null.
#completed_atstring | nullAlwaysISO 8601 UTC timestamp when the turn finished, or null while processing.
#errorobject | nullAlwaysFailure details when status is failed, or null otherwise.
Show all 23 fields (15 more)
FieldTypePresentDescription
#error.codestringAlwaysStable 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.messagestringAlwaysHuman-readable message explaining why the turn failed.
#replystringSometimesAssistant reply text to show the user (present when status is complete, up to 1,200 characters).
#proposalsarraySometimesProposed transcript edit groups referencing words[].id (present when status is complete).Fields below
#momentsarraySometimesNotable timestamps referenced in the answer (up to 8 items, present when status is complete).Fields below
#unclear_word_idsarraySometimesWord IDs that an audio listening pass found hard to understand.
#speaker_turnsarraySometimesDetected speaker turn starts keyed by word_id.
#speaker_turns[].word_idstringSometimesFirst word ID of the speaker turn.
#speaker_turns[].speakerstringSometimesSpeaker label for the turn.
#shorteningobject | nullSometimesSuggested tighten settings for audio projects, or null.Fields below
#feedback_offerobject | nullSometimesOptional prompt inviting user feedback when the assistant detects a product report, or null; send the report with Send assistant feedback.
#feedback_offer.kindstringSometimesFeedback category (bug, feature, or other).bugfeatureother
#feedback_offer.summarystringSometimesSuggested one-line summary for the feedback report.
#noticesarraySometimesInformational notices returned alongside the answer.
#windows_totalintegerSometimesTotal 30-second windows that the current draft plus all proposals would restore.
proposals[] 13 fields
FieldTypePresentDescription
#proposals[].idstringSometimesIdentifier of the proposal.
#proposals[].titlestringSometimesShort title summarizing the proposed edits.
#proposals[].iconstringSometimesCategory icon identifier for the proposal.fillerreplacerephrasemuteregenerategrammarcleanupinsert
#proposals[].changesarraySometimesOrdered word-level changes in this proposal.
#proposals[].changes[].idstringSometimesIdentifier of the change.
#proposals[].changes[].kindstringSometimesChange action: replace, remove, insert, or regenerate.replaceremoveinsertregenerate
#proposals[].changes[].word_idsarraySometimesOrdered words[].id values covered by this change.
#proposals[].changes[].beforestringSometimesOriginal words before the change.
#proposals[].changes[].afterstringSometimesWords after the change, or "" when removing words.
#proposals[].changes[].reasonstringSometimesShort reason explaining the change.
#proposals[].changes[].start_secondsnumber | nullSometimesStart timestamp in seconds on the recording, or null.
#proposals[].changes[].end_secondsnumber | nullSometimesEnd timestamp in seconds on the recording, or null.
#proposals[].windowsintegerSometimesAdditional 30-second restore windows this proposal adds to an edit.
moments[] 4 fields
FieldTypePresentDescription
#moments[].start_secondsnumberSometimesMoment start time in seconds.
#moments[].end_secondsnumber | nullSometimesMoment end time in seconds, or null.
#moments[].labelstringSometimesShort label describing the moment.
#moments[].word_idstring | nullSometimesAssociated words[].id, or null.
shortening 4 fields
FieldTypePresentDescription
#shortening.close_removed_gapsbooleanSometimesWhether to close silence left by removed words.
#shortening.max_pause_secondsnumber | nullSometimesSuggested maximum pause length in seconds, or null.
#shortening.estimated_secondsnumberSometimesEstimated seconds saved by applying the shortening.
#shortening.reasonstringSometimesExplanation for the shortening suggestion.

Response 200OK.

Successful response
{
  "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

  • 200OK.
    Returns the assistant turn (processing, or 2 more causes
    • Returns the assistant turn (processing
    • complete
    • failed)
  • 400Bad request.Diffio-End-User exceeds 128 characters. invalid_header
  • 403Forbidden: the key lacks permission.Key is inactive or lacks generations:read. permission_denied
  • 404Not found.
    Project not found, or 2 more causes
    • Project not found
    • Generation not found
    • Turn not found
    project_not_foundgeneration_not_foundtranscript_assistant_turn_not_found
  • 401Unauthorized: the API key is missing or invalid.405Client error.Same on every endpoint
    • 401Unauthorized: the API key is missing or invalid. Missing API key (code missing_api_key), or invalid API key (code invalid_api_key).
    • 405Client error. 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 401Unauthorized: the API key is missing or invalid.:

Error response
{
  "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 or listen for transcript_assistant_turn.completed and transcript_assistant_turn.failed webhooks.

Report an issue with this page