Segments

A segment is one stretch of speech, usually a sentence or two, with its own start and end time. The transcript is the list of segments in order.

Read segments

GET /transcriptions/{id}/segments

Query parameter	Default	Notes
fromSeq	0	Return segments whose seq is at least this number. Must be a non-negative integer.
limit	500	Segments per page, 1 to 2000.
includeWords	true	Set to false to leave out word timings. Pages are much smaller.

An invalid value for any of these is 400 VALIDATION_ERROR with reason invalid for that field.

curl -sS "https://api.scribewren.com/v1/transcriptions/$TX_ID/segments?fromSeq=0&limit=500&includeWords=false" \
  -H "Authorization: Bearer $SCRIBEWREN_API_KEY"

{
  "success": true,
  "code": 200,
  "message": "OK",
  "data": {
    "segments": [
      {
        "id": "019a4f2e-b310-7e55-a1c4-0d7f9c2e6b88",
        "seq": 0,
        "startMs": 0,
        "endMs": 2140,
        "speakerId": "019a4f2e-8a10-7c4b-9e21-6f0b3d5a7c11",
        "text": "Welcome to the show.",
        "words": null,
        "edited": false,
        "version": 1
      }
    ],
    "nextSeq": 1
  },
  "error": null,
  "meta": {
    "requestId": "019a4f30-1c22-7a10-b5d3-42f1c0a8e777",
    "timestamp": "2026-12-01T09:41:07.512Z"
  }
}

Page through the transcript

Segments are numbered by seq, starting at 0. A page returns up to limit segments in seq order. If more remain, nextSeq is the seq of the first segment of the next page. On the last page nextSeq is null.

To read everything, start with fromSeq=0 and repeat with fromSeq set to nextSeq until nextSeq is null. Quickstart shows this loop.

Use the nextSeq value you were given. Do not compute the next position yourself from the number of segments you received.

The segment object

Field	Type	Notes
id	string	UUID.
seq	integer	Position in the transcript, from 0.
startMs	integer	Start time from the beginning of the media, in milliseconds.
endMs	integer	End time, in milliseconds.
speakerId	string or null	Refers to an entry of speakers in the transcription detail. null when no speaker was identified.
text	string	The text of the segment.
words	array or null	Word timings. null when you pass includeWords=false.
edited	boolean	true if the text was edited in the app after transcription.
version	integer	Increases each time the segment is edited.

Each entry of words has:

Field	Type	Notes
word	string	The word as spoken, with its punctuation.
startMs	integer	Start time in milliseconds.
endMs	integer	End time in milliseconds.
confidence	number or null	From 0 to 1. null when no score is available, for example after the segment was edited and its words were re-timed.

To show speaker names, call GET /transcriptions/{id} once and map speakerId to speakers[].displayName.

When the transcript is not ready

While the job is queued or running, or when it ended as failed or canceled, there is no transcript to read. The call returns 409 INVALID_STATE_TRANSITION with error.details.reason set to not_ready. Wait for status to become succeeded first. See Transcriptions.

Other errors: 404 NOT_FOUND for an unknown ID or another account’s transcription, and 429 RATE_LIMITED. See Errors.

Read only

This API returns segments but does not edit them. Text edits and speaker renames are made in the app. A later read returns the edited text and a higher version.