Skip to main content
GET
/
transcriptions
/
{id}
curl https://api.bota.dev/v1/transcriptions/txn_abc123 \
  -H "Authorization: Bearer sk_live_..."

{
  "id": "txn_abc123",
  "recording_id": "rec_abc123",
  "status": "pending",
  "language": "en",
  "provider": "whisper",
  "duration_ms": null,
  "segments": null,
  "text": null,
  "error": null,
  "created_at": "2025-01-15T10:10:00Z",
  "completed_at": null
}
Retrieve the status and result of a transcription job. Poll this endpoint until status is completed or failed.

​
Authentication

Requires an API key with transcriptions:read scope. 
curl https://api.bota.dev/v1/transcriptions/txn_abc123 \
  -H "Authorization: Bearer sk_live_..."

​
Path Parameters

​
id
string
required
The transcription’s unique identifier (e.g., txn_abc123).

​
Response

Returns the transcription object including its current status and, when completed, the full transcript text and segments. 
{
  "id": "txn_abc123",
  "recording_id": "rec_abc123",
  "status": "pending",
  "language": "en",
  "provider": "whisper",
  "duration_ms": null,
  "segments": null,
  "text": null,
  "error": null,
  "created_at": "2025-01-15T10:10:00Z",
  "completed_at": null
}

​
Response Fields

FieldTypeDescription
idstringThe transcription’s unique identifier (e.g., txn_abc123)
recording_idstringThe recording this transcription belongs to
statusstringCurrent status: pending, processing, completed, or failed
languagestring | nullLanguage code used for transcription
providerstringASR provider used (e.g., whisper, deepgram)
duration_msinteger | nullAudio duration in milliseconds (populated on completion)
segmentsarray | nullArray of transcript segments with speaker labels and timestamps (populated on completion)
textstring | nullFull transcript text (populated on completion)
errorobject | nullError details if the transcription failed
created_atstringISO 8601 timestamp when the transcription was created
completed_atstring | nullISO 8601 timestamp when the transcription completed or failed

​
Transcript Segment Fields

FieldTypeDescription
textstringTranscribed text for this segment
speakerstringSpeaker identifier (e.g., SPEAKER_0, SPEAKER_1)
startfloatStart time in seconds
endfloatEnd time in seconds
confidencefloatConfidence score (0-1)

​
Example: Processing Segments

// Group by speaker
const byeSpeaker = {};
for (const segment of transcription.segments) {
  if (!byeSpeaker[segment.speaker]) {
    byeSpeaker[segment.speaker] = [];
  }
  byeSpeaker[segment.speaker].push(segment.text);
}

// Format as conversation
const conversation = transcription.segments
  .map(s => `${s.speaker}: ${s.text}`)
  .join('\n');

console.log(conversation);
// SPEAKER_0: Hello, thanks for joining us today.
// SPEAKER_1: Happy to be here. Let's get started.
// SPEAKER_0: So, tell me about your background.

​
Error Codes

CodeDescription
audio_too_shortAudio is less than 1 second
audio_corruptAudio file is corrupt or unreadable
unsupported_formatAudio format not supported
processing_errorInternal processing error