> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bota.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Transcription

> Retrieve the status and result of a transcription job

Retrieve the status and result of a transcription job. Poll this endpoint until status is `completed` or `failed`.

## Authentication

Requires an [API key](/authentication) with `transcriptions:read` scope.

<RequestExample>
  ```bash cURL theme={null}
  curl https://api.bota.dev/v1/transcriptions/txn_abc123 \
    -H "Authorization: Bearer sk_live_..."
  ```

  ```javascript Node.js theme={null}
  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);
  }
  ```

  ```python Python theme={null}
  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'])
  ```
</RequestExample>

## Path Parameters

<ParamField path="id" type="string" required>
  The transcription's unique identifier (e.g., `txn_abc123`).
</ParamField>

## Response

Returns the transcription object including its current status and, when completed, the full transcript text and segments.

<ResponseExample>
  ```json 200 (pending) theme={null}
  {
    "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
  }
  ```

  ```json 200 (processing) theme={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
  }
  ```

  ```json 200 (completed) theme={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"
  }
  ```

  ```json 200 (failed) theme={null}
  {
    "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"
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "not_found",
      "message": "Transcription not found"
    }
  }
  ```
</ResponseExample>

## 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

```javascript theme={null}
// 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           |