Get Transcription

curl https://api.bota.dev/v1/transcriptions/txn_abc123 \
  -H "Authorization: Bearer sk_live_..."

const response = await fetch('https://api.bota.dev/v1/transcriptions/txn_abc123', {
  headers: {
    'Authorization': 'Bearer sk_live_...',
  },
});

const transcription = await response.json();

if (transcription.status === 'completed') {
  console.log(transcription.text);
  console.log(transcription.segments);
}

import requests

response = requests.get(
    'https://api.bota.dev/v1/transcriptions/txn_abc123',
    headers={'Authorization': 'Bearer sk_live_...'},
)

transcription = response.json()

if transcription['status'] == 'completed':
    print(transcription['text'])

{
  "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
}

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

{
  "id": "txn_abc123",
  "recording_id": "rec_abc123",
  "status": "completed",
  "language": "en",
  "provider": "whisper",
  "duration_ms": 1800000,
  "segments": [
    {
      "text": "Hello, thanks for joining us today.",
      "speaker": "SPEAKER_0",
      "start": 0.0,
      "end": 2.5,
      "confidence": 0.95
    },
    {
      "text": "Happy to be here. Let's get started.",
      "speaker": "SPEAKER_1",
      "start": 2.8,
      "end": 5.2,
      "confidence": 0.92
    },
    {
      "text": "So, tell me about your background.",
      "speaker": "SPEAKER_0",
      "start": 5.5,
      "end": 7.8,
      "confidence": 0.97
    }
  ],
  "text": "Hello, thanks for joining us today. Happy to be here. Let's get started. So, tell me about your background.",
  "error": null,
  "created_at": "2025-01-15T10:10:00Z",
  "completed_at": "2025-01-15T10:15:00Z"
}

{
  "id": "txn_abc123",
  "recording_id": "rec_abc123",
  "status": "failed",
  "language": null,
  "provider": "whisper",
  "duration_ms": null,
  "segments": null,
  "text": null,
  "error": {
    "code": "audio_too_short",
    "message": "Audio file is too short to transcribe (minimum 1 second)"
  },
  "created_at": "2025-01-15T10:10:00Z",
  "completed_at": "2025-01-15T10:10:05Z"
}

{
  "error": {
    "code": "not_found",
    "message": "Transcription not found"
  }
}

GET

transcriptions

{id}

curl https://api.bota.dev/v1/transcriptions/txn_abc123 \
  -H "Authorization: Bearer sk_live_..."

const response = await fetch('https://api.bota.dev/v1/transcriptions/txn_abc123', {
  headers: {
    'Authorization': 'Bearer sk_live_...',
  },
});

const transcription = await response.json();

if (transcription.status === 'completed') {
  console.log(transcription.text);
  console.log(transcription.segments);
}

import requests

response = requests.get(
    'https://api.bota.dev/v1/transcriptions/txn_abc123',
    headers={'Authorization': 'Bearer sk_live_...'},
)

transcription = response.json()

if transcription['status'] == 'completed':
    print(transcription['text'])

{
  "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
}

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

{
  "id": "txn_abc123",
  "recording_id": "rec_abc123",
  "status": "completed",
  "language": "en",
  "provider": "whisper",
  "duration_ms": 1800000,
  "segments": [
    {
      "text": "Hello, thanks for joining us today.",
      "speaker": "SPEAKER_0",
      "start": 0.0,
      "end": 2.5,
      "confidence": 0.95
    },
    {
      "text": "Happy to be here. Let's get started.",
      "speaker": "SPEAKER_1",
      "start": 2.8,
      "end": 5.2,
      "confidence": 0.92
    },
    {
      "text": "So, tell me about your background.",
      "speaker": "SPEAKER_0",
      "start": 5.5,
      "end": 7.8,
      "confidence": 0.97
    }
  ],
  "text": "Hello, thanks for joining us today. Happy to be here. Let's get started. So, tell me about your background.",
  "error": null,
  "created_at": "2025-01-15T10:10:00Z",
  "completed_at": "2025-01-15T10:15:00Z"
}

{
  "id": "txn_abc123",
  "recording_id": "rec_abc123",
  "status": "failed",
  "language": null,
  "provider": "whisper",
  "duration_ms": null,
  "segments": null,
  "text": null,
  "error": {
    "code": "audio_too_short",
    "message": "Audio file is too short to transcribe (minimum 1 second)"
  },
  "created_at": "2025-01-15T10:10:00Z",
  "completed_at": "2025-01-15T10:10:05Z"
}

{
  "error": {
    "code": "not_found",
    "message": "Transcription not found"
  }
}

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_..."

const response = await fetch('https://api.bota.dev/v1/transcriptions/txn_abc123', {
  headers: {
    'Authorization': 'Bearer sk_live_...',
  },
});

const transcription = await response.json();

if (transcription.status === 'completed') {
  console.log(transcription.text);
  console.log(transcription.segments);
}

import requests

response = requests.get(
    'https://api.bota.dev/v1/transcriptions/txn_abc123',
    headers={'Authorization': 'Bearer sk_live_...'},
)

transcription = response.json()

if transcription['status'] == 'completed':
    print(transcription['text'])

Path Parameters

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
}

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

{
  "id": "txn_abc123",
  "recording_id": "rec_abc123",
  "status": "completed",
  "language": "en",
  "provider": "whisper",
  "duration_ms": 1800000,
  "segments": [
    {
      "text": "Hello, thanks for joining us today.",
      "speaker": "SPEAKER_0",
      "start": 0.0,
      "end": 2.5,
      "confidence": 0.95
    },
    {
      "text": "Happy to be here. Let's get started.",
      "speaker": "SPEAKER_1",
      "start": 2.8,
      "end": 5.2,
      "confidence": 0.92
    },
    {
      "text": "So, tell me about your background.",
      "speaker": "SPEAKER_0",
      "start": 5.5,
      "end": 7.8,
      "confidence": 0.97
    }
  ],
  "text": "Hello, thanks for joining us today. Happy to be here. Let's get started. So, tell me about your background.",
  "error": null,
  "created_at": "2025-01-15T10:10:00Z",
  "completed_at": "2025-01-15T10:15:00Z"
}

{
  "id": "txn_abc123",
  "recording_id": "rec_abc123",
  "status": "failed",
  "language": null,
  "provider": "whisper",
  "duration_ms": null,
  "segments": null,
  "text": null,
  "error": {
    "code": "audio_too_short",
    "message": "Audio file is too short to transcribe (minimum 1 second)"
  },
  "created_at": "2025-01-15T10:10:00Z",
  "completed_at": "2025-01-15T10:10:05Z"
}

{
  "error": {
    "code": "not_found",
    "message": "Transcription not found"
  }
}

Response Fields

Field	Type	Description
`id`	string	The transcription’s unique identifier (e.g., `txn_abc123`)
`recording_id`	string	The recording this transcription belongs to
`status`	string	Current status: `pending`, `processing`, `completed`, or `failed`
`language`	string \| null	Language code used for transcription
`provider`	string	ASR provider used (e.g., `whisper`, `deepgram`)
`duration_ms`	integer \| null	Audio duration in milliseconds (populated on completion)
`segments`	array \| null	Array of transcript segments with speaker labels and timestamps (populated on completion)
`text`	string \| null	Full transcript text (populated on completion)
`error`	object \| null	Error details if the transcription failed
`created_at`	string	ISO 8601 timestamp when the transcription was created
`completed_at`	string \| null	ISO 8601 timestamp when the transcription completed or failed

Transcript Segment Fields

Field	Type	Description
`text`	string	Transcribed text for this segment
`speaker`	string	Speaker identifier (e.g., `SPEAKER_0`, `SPEAKER_1`)
`start`	float	Start time in seconds
`end`	float	End time in seconds
`confidence`	float	Confidence 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

Code	Description
`audio_too_short`	Audio is less than 1 second
`audio_corrupt`	Audio file is corrupt or unreadable
`unsupported_format`	Audio format not supported
`processing_error`	Internal processing error

Create Transcription Create Summary

​Authentication

​Path Parameters

​Response

​Response Fields

​Transcript Segment Fields

​Example: Processing Segments

​Error Codes