Transcriptions

A transcription is the job that turns an uploaded file into a transcript. You get its ID from POST /media/{id}/complete, see Uploads. These endpoints let you follow the job and manage it.

Status and stage

status is one of:

Status	Meaning
queued	Waiting for a free worker. queuePosition says where.
running	Being processed. stage and progress update as it goes.
succeeded	Done. The transcript is ready to read and export.
failed	Stopped with an error. errorCode says why.
canceled	Stopped by a cancel request.

succeeded, failed and canceled are final. A final job changes only if you retry it.

While running, stage is one of downloading, preprocessing, transcribing, diarizing and finalizing, in that order. Outside running it is null. progress is an integer from 0 to 100.

Wait for a final status by polling GET /transcriptions/{id} every few seconds, or let webhooks tell you. Do not poll in a tight loop: see Rate limits.

Get a transcription

GET /transcriptions/{id}

Returns the transcription and a few extra fields.

{
  "id": "019a4f2e-7c1b-7d3a-9f00-3c5e8a1b2d4f",
  "mediaId": "019a4f2d-e5a0-7b42-8c11-6d2f0e9a7b13",
  "title": "interview",
  "status": "running",
  "stage": "transcribing",
  "progress": 42,
  "queuePosition": null,
  "languageRequested": "auto",
  "language": null,
  "durationMs": null,
  "sourceDurationMs": null,
  "truncated": false,
  "speakerCount": 0,
  "segmentCount": 0,
  "wordCount": 0,
  "warnings": [],
  "errorCode": null,
  "isSample": false,
  "canRetry": false,
  "folderId": null,
  "createdAt": "2026-12-01T09:41:07.512Z",
  "updatedAt": "2026-12-01T09:42:31.004Z",
  "completedAt": null,
  "canceledAt": null
}

This object is the data field of the usual envelope. The detail response also carries languageProbability, diarization, expectedSpeakers, contentVersion and speakers.

Transcription fields

Field	Type	Notes
id	string	UUID.
mediaId	string	The uploaded file this job processes.
title	string	Up to 200 characters. It starts as the file name without its extension.
status	string	See above.
stage	string or null	See above.
progress	integer	0 to 100.
queuePosition	integer or null	1 means next. Set only while queued. It is an estimate.
languageRequested	string	The language you sent, auto by default.
language	string or null	The detected or requested language code, once known.
durationMs	integer or null	How much audio was transcribed.
sourceDurationMs	integer or null	The full length of the media.
truncated	boolean	true when durationMs is less than sourceDurationMs because the file was longer than the plan’s maximum duration.
speakerCount	integer	Number of speakers found.
segmentCount	integer	Number of segments.
wordCount	integer	Number of words.
warnings	array of strings	Non-fatal notices. See below.
errorCode	string or null	Set only when status is failed. See below.
isSample	boolean	true for the sample transcription added from the app.
canRetry	boolean	true when the job is failed or canceled and the original file still exists.
folderId	string or null	The app folder that holds the transcription, if any.
createdAt, updatedAt	string	UTC timestamps.
completedAt, canceledAt	string or null	UTC timestamps.

The detail response adds:

Field	Type	Notes
languageProbability	number or null	Confidence in language, from 0 to 1.
diarization	boolean	Whether speaker labels were requested.
expectedSpeakers	integer or null	The hint you sent, if any.
contentVersion	integer	Increases when the transcript changes.
speakers	array	Objects with id, ordinal and displayName. Segments refer to speakers by id.

The detail response also has playback, notes and translations fields. They describe app features that this API does not serve, so you can ignore them.

Error codes

errorCode is one of:

Value	Meaning
MEDIA_UNREADABLE	The file could not be decoded.
NO_AUDIO_STREAM	The file has no audio track.
INTERNAL_ERROR	An unexpected failure on our side. Retry the job.
WORKER_TIMEOUT	Processing took too long and was stopped.

These values are inside the transcription object. They are different from the error.code of a failed API request. See Errors.

Warnings

warnings can contain these values. The job still succeeds.

Value	Meaning
DIARIZATION_FAILED	Speaker labels could not be added.
NO_SPEECH_DETECTED	No speech was found.
LANGUAGE_LOW_CONFIDENCE	The detected language is uncertain.

List transcriptions

GET /transcriptions

Returns a page of transcriptions, newest first by default. The response uses the standard pagination fields in meta.

Query parameter	Notes
page	Page number, from 1.
limit	Items per page, 1 to 100. The default is 25.
q	Case-insensitive title search, up to 200 characters.
status	One or more statuses, separated by commas, such as queued,running.
sort	newest (default), oldest or title. Any other value is VALIDATION_ERROR with reason invalid_enum.
folderId	An app folder ID, or none for transcriptions that are not in a folder. Any other value is VALIDATION_ERROR.

curl -sS "https://api.scribewren.com/v1/transcriptions?status=succeeded&limit=10" \
  -H "Authorization: Bearer $SCRIBEWREN_API_KEY"

Cancel a transcription

POST /transcriptions/{id}/cancel

Stops a queued or running job and returns the updated transcription with status set to canceled. Any other status returns 409 INVALID_STATE_TRANSITION with details.status and details.action.

If the job never started, or ran for 60 seconds or less, the cancel does not count toward the daily limit.

Retry a transcription

POST /transcriptions/{id}/retry

Queues a failed or canceled job again and returns it with status set to queued. A retry counts as a new start toward the daily limit. Check canRetry first.

Error	Status	When
INVALID_STATE_TRANSITION	409	The job is not failed or canceled.
MEDIA_EXPIRED	410	The original file was already deleted. details.object is original. Upload the file again.
PLAN_LIMIT_EXCEEDED	403	A plan limit blocks a new start.
ACCOUNT_RESTRICTED	403	The account cannot start new processing.
SERVICE_UNAVAILABLE	503	New processing is paused (details.reason is uploads_paused).

Delete a transcription

DELETE /transcriptions/{id}

Deletes the transcription and its transcript. If the job is still queued or running, it is canceled first. The response is 200 with data set to null. Stored files are removed within 24 hours.

Deleting cannot be undone

There is no trash and no restore for a deleted transcription. Export what you need first.

Not in the API

You cannot rename a transcription, edit segments, change speaker names, or manage folders through this API. Those actions are available in the app.