Skip to main content
POST
/
recordings
/
{id}
/
transcribe
curl -X POST https://api.bota.dev/v1/recordings/rec_abc123/transcribe \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "language": "en",
    "diarization": true
  }'

{
  "id": "txn_abc123",
  "recording_id": "rec_abc123",
  "status": "pending",
  "language": "en",
  "duration_ms": null,
  "segments": null,
  "text": null,
  "error": null,
  "created_at": "2025-01-15T10:10:00Z",
  "completed_at": null
}
Start an asynchronous transcription job for a recording. The recording must be in uploaded status. Use webhooks to receive real-time notifications when the transcription completes, or poll the Get Transcription endpoint.
​
id
string
required
The recording’s unique identifier (e.g., rec_abc123).
​
language
string
ISO 639-1 language code (e.g., en, es, zh). If not specified, the language is auto-detected.
​
diarization
boolean
default:"true"
Enable speaker diarization to identify different speakers in the transcript.
curl -X POST https://api.bota.dev/v1/recordings/rec_abc123/transcribe \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "language": "en",
    "diarization": true
  }'

{
  "id": "txn_abc123",
  "recording_id": "rec_abc123",
  "status": "pending",
  "language": "en",
  "duration_ms": null,
  "segments": null,
  "text": null,
  "error": null,
  "created_at": "2025-01-15T10:10:00Z",
  "completed_at": null
}

​
Transcription Status

StatusDescription
pendingJob queued, waiting to start
processingTranscription in progress
completedTranscription finished successfully
failedTranscription failed (check error field)

​
Polling for Results

After starting a transcription job, poll the Get Transcription endpoint: 
async function waitForTranscription(transcriptionId) {
  while (true) {
    const response = await fetch(
      `https://api.bota.dev/v1/transcriptions/${transcriptionId}`,
      { headers: { 'Authorization': 'Bearer sk_live_...' } }
    );

    const transcription = await response.json();

    if (transcription.status === 'completed') {
      return transcription;
    }

    if (transcription.status === 'failed') {
      throw new Error(transcription.error.message);
    }

    // Wait 2 seconds before polling again
    await new Promise(resolve => setTimeout(resolve, 2000));
  }
}
Transcription typically takes 10-30% of the audio duration. A 30-minute recording usually completes in 3-10 minutes.
For production use, subscribe to webhook events instead of polling: See Webhooks Overview for setup instructions.