Features

Prompting guide

The speech understanding endpoint in depth: request fields, response shape, JSON output, and errors.

POST/v2/speech-understandingAsk a question about a completed transcript

One endpoint answers any question about a completed transcript. This page is the full reference: every request field, the response shape, how grounding behaves, and how to get reliable JSON output.

Request

Field	Type	Required	Description
`transcript_id`	string	Yes	Id of a transcript created through `POST /v2/transcripts` on the same account. The transcript must be `completed` and contain text.
`prompt`	string	Yes	The question or instruction, 1 to 8,000 characters.
`model`	string	No	Optional model override. Omit it to use the default model.
`response_format`	string	No	`"text"` (default) or `"json"`. With `"json"`, describe the object you want in the prompt and parse the `response` string.

Response

Field	Type	Description
`id`	string	Id of this speech understanding result.
`transcript_id`	string	The transcript that was analyzed.
`model`	string	The model that produced the answer.
`response`	string	The answer. With `response_format: "json"` this is a JSON string to parse.
`created_at`	string	ISO 8601 timestamp.

Example response

{
  "id": "su_9f2c31ab",
  "transcript_id": "tr_abc123",
  "model": "default",
  "response": "Three decisions were made. 1) Ship the beta on Friday (owner: Dana). 2) Move the retro to Tuesdays (owner: Sam). 3) Pause the ads experiment (owner: Priya).",
  "created_at": "2026-07-22T14:03:11Z"
}

Grounded answers

The endpoint instructs the model to answer strictly from the transcript. When the transcript does not contain the answer, the response says the transcript does not provide enough information rather than guessing. This makes the endpoint safe for factual workflows such as compliance review and QA scoring.

Writing good prompts

State the output format. Say bullet points, a table, one sentence, or a JSON object. Unstated formats produce free-form prose.
Bound the length. Phrases like at most five bullets or under 100 words keep responses consistent across recordings.
Ask for evidence. Quote the line that supports each claim makes answers auditable against the transcript.
One task per call. A summary call and an action-item call are cheaper to maintain than one prompt that does both and drifts.
Use the audience. Explain this to a new customer support agent changes vocabulary and detail level.

JSON output

Set response_format to "json" and name every key you expect in the prompt, including types and allowed values. The response field then contains a JSON string. Always parse it inside a try block: the object shape follows your prompt, so a vague prompt yields a loose object.

Errors

Status	Code	When
`404`	`not_found`	The transcript id does not exist, belongs to another account, or was not created through `POST /v2/transcripts`.
`409`	`not_ready`	The transcript is still processing, errored, or has no text yet.
`422`	validation error	The prompt is empty or longer than 8,000 characters, or a field has the wrong type.

Error shape

{
  "error": {
    "message": "Transcript is not ready yet.",
    "code": "not_ready"
  }
}