# Batch Transcription resource

> \[!IMPORTANT]
>
> Batch Transcription Configurations use artificial intelligence or machine learning technologies. By enabling or using any of these features or functionalities within Batch Transcription Configurations, you acknowledge and agree that your use of these features or functionalities is subject to the terms of the [Predictive and Generative AI/ML Features Addendum](https://www.twilio.com/en-us/legal/ai-terms/predictive-generative-ai-features).
>
> Batch Transcription Configurations is currently available as a Public Beta release and the information contained in this document is subject to change. Some features are not yet implemented and others may be changed before the product is declared as Generally Available. Public Beta products are not covered by the Twilio Support Terms or Twilio Service Level Agreement.
>
> Batch Transcription Configurations is not PCI compliant or a HIPAA Eligible Service and should not be used in workflows that are subject to HIPAA or PCI.

A Batch Transcription resource represents an asynchronous transcription job for a recorded conversation. To submit audio for transcription, call the [Create a Transcription](#create-a-transcription) endpoint. You can transcribe Twilio Recordings using a Recording SID, or provide a direct URL to an externally hosted audio file.

## Audio channel formats

Batch Transcription supports several audio formats, each suited for different needs:

* **Mono**: a single audio channel, suitable for straightforward recordings where speaker differentiation isn't crucial.
* **Stereo**: two channels that provide spatial sound but don't separate speakers.
* **Dual-channel**: two distinct audio tracks in the same file, ideal for differentiating speakers such as agents and customers in call recordings. This format improves transcription accuracy and participant differentiation.

For better transcription accuracy, use dual-channel recordings, especially when speaker differentiation is important.

## Transcribe a Twilio Recording

To transcribe a Twilio Recording, provide the Recording SID in the `sourceId` parameter.

### Limits for Twilio Recording transcriptions

* The recording file size must not exceed 3 GB.
* Audio duration can't exceed eight hours.
* Recordings shorter than two seconds aren't transcribed.
* To transcribe Twilio Recordings stored in external storage, use the `mediaUrl` parameter. The `sourceId` parameter isn't supported for externally stored Twilio Recordings.
* You can't transcribe [encrypted Voice Recordings](/docs/voice/tutorials/voice-recording-encryption). Move those recordings to your own external storage, generate pre-signed URLs for the decrypted files, and use the `mediaUrl` parameter instead.

## Transcribe an external recording

To transcribe a recording stored externally, provide the recording's URL in the `mediaUrl` parameter.

Batch Transcription supports both mono and stereo audio for the following formats:

* WAV (PCM-encoded)
* MP3
* FLAC

### Limits for external recordings

* The maximum file size allowed is 3 GB.
* The maximum audio length is eight hours.
* The minimum sample rate required is 8 kHz (telephony grade). For best results, use 16 kHz.

> \[!WARNING]
>
> You must provide either `sourceId` or `mediaUrl`, but not both.

## Specify participant information

Optionally, provide a `participants` array to identify who is on each audio channel. Each participant requires an `audioChannelIndex` (1 or 2) and can include a `type` (`CUSTOMER`, `HUMAN_AGENT`, or `AI_AGENT`), `address`, and `name`.

When `sourceId` is provided, participant data is inferred from the call metadata.

When `mediaUrl` is provided, participant data can't be resolved from the source and must be supplied explicitly. If the transcription result is stored in a conversation through a `conversationConfigurationId`, participant information is required. Without it, Twilio can't correctly attribute the transcript to conversation participants.

## Create a Transcription

```text
POST https://voice.twilio.com/v3/Transcriptions
```

> \[!NOTE]
>
> A `transcriptionConfigurationId` is required to create a Transcription. This ID identifies the configuration that controls transcription behavior such as engine, language, and callbacks. See the [Transcription Configuration resource](/docs/configurations/transcription-configuration-resource) for details.

### Create a Transcription with a Recording SID

To submit a Twilio Recording for transcription, provide the Recording SID in `sourceId`.

```bash
curl -X POST https://voice.twilio.com/v3/Transcriptions \
  -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transcriptionConfigurationId": "voice_transcriptionconfiguration_5pe8jw3ahdmsh7zr06yh4d45x1",
    "sourceId": "RExxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "participants": [
      { "audioChannelIndex": 1, "type": "CUSTOMER", "address": "+15551234567", "name": "Jane Doe" },
      { "audioChannelIndex": 2, "type": "HUMAN_AGENT", "address": "+15559876543", "name": "Agent Smith" }
    ]
  }'
```

```json
{
  "status": "PENDING",
  "statusUrl": "https://voice.twilio.com/v3/Transcriptions/voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa",
  "transcription": {
    "id": "voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa",
    "accountId": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "status": "PENDING",
    "transcriptionConfigurationId": "voice_transcriptionconfiguration_5pe8jw3ahdmsh7zr06yh4d45x1",
    "sourceId": "RExxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "mediaUrl": null,
    "audioStartedAt": "2026-03-10T19:42:16Z",
    "conversationId": null,
    "participants": [
      { "audioChannelIndex": 1, "type": "CUSTOMER", "address": "+15551234567", "name": "Jane Doe" },
      { "audioChannelIndex": 2, "type": "HUMAN_AGENT", "address": "+15559876543", "name": "Agent Smith" }
    ],
    "duration": null,
    "resolvedConfiguration": {
      "transcriptionEngine": "deepgram",
      "speechModel": "nova-3",
      "language": "en-US",
      "transcriptionStatusCallback": {
        "url": "https://example.com/transcription/callback",
        "method": "POST",
        "events": null
      },
      "conversationConfigurationId": "conv_configuration_5pe8jw3ahdmsh7zr06yh4d45x1",
      "participantDefaults": [
        { "audioChannelIndex": 1, "type": "CUSTOMER" },
        { "audioChannelIndex": 2, "type": "HUMAN_AGENT" }
      ]
    },
    "createdAt": "2026-04-02T19:25:20Z",
    "updatedAt": "2026-04-02T19:25:20Z",
    "url": "https://voice.twilio.com/v3/Transcriptions/voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa"
  }
}
```

### Create a Transcription with a media URL

To submit an externally hosted audio file for transcription, provide its URL in `mediaUrl`.

```bash
curl -X POST https://voice.twilio.com/v3/Transcriptions \
  -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transcriptionConfigurationId": "voice_transcriptionconfiguration_5pe8jw3ahdmsh7zr06yh4d45x1",
    "mediaUrl": "https://example.com/audio/recording.wav",
    "audioStartedAt": "2026-03-10T19:42:16Z",
    "participants": [
      { "audioChannelIndex": 1, "type": "CUSTOMER", "address": "+15551234567", "name": "Jane Doe" },
      { "audioChannelIndex": 2, "type": "HUMAN_AGENT", "address": "+15559876543", "name": "Agent Smith" }
    ]
  }'
```

```json
{
  "status": "PENDING",
  "statusUrl": "https://voice.twilio.com/v3/Transcriptions/voice_transcription_4abcde1234567890abcde12345",
  "transcription": {
    "id": "voice_transcription_4abcde1234567890abcde12345",
    "accountId": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "status": "PENDING",
    "transcriptionConfigurationId": "voice_transcriptionconfiguration_5pe8jw3ahdmsh7zr06yh4d45x1",
    "sourceId": null,
    "mediaUrl": "https://example.com/audio/recording.wav",
    "audioStartedAt": "2026-03-10T19:42:16Z",
    "conversationId": null,
    "participants": [
      { "audioChannelIndex": 1, "type": "CUSTOMER", "address": "+15551234567", "name": "Jane Doe" },
      { "audioChannelIndex": 2, "type": "HUMAN_AGENT", "address": "+15559876543", "name": "Agent Smith" }
    ],
    "duration": null,
    "resolvedConfiguration": {
      "transcriptionEngine": "deepgram",
      "speechModel": "nova-3",
      "language": "en-US",
      "transcriptionStatusCallback": {
        "url": "https://example.com/transcription/callback",
        "method": "POST",
        "events": null
      },
      "conversationConfigurationId": "conv_configuration_5pe8jw3ahdmsh7zr06yh4d45x1",
      "participantDefaults": [
        { "audioChannelIndex": 1, "type": "CUSTOMER" },
        { "audioChannelIndex": 2, "type": "HUMAN_AGENT" }
      ]
    },
    "createdAt": "2026-04-02T19:25:20Z",
    "updatedAt": "2026-04-02T19:25:20Z",
    "url": "https://voice.twilio.com/v3/Transcriptions/voice_transcription_4abcde1234567890abcde12345"
  }
}
```

## Fetch a Transcription

> \[!NOTE]
>
> Use the `statusUrl` from the response to poll for progress. The response includes a `Retry-After` header with the recommended number of seconds to wait before polling again.

```text
GET https://voice.twilio.com/v3/Transcriptions/{transcriptionId}
```

```bash
curl -X GET "https://voice.twilio.com/v3/Transcriptions/voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa" \
  -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN"
```

```json
{
  "operationId": "voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa",
  "status": "COMPLETED",
  "statusUrl": "https://voice.twilio.com/v3/Transcriptions/voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa",
  "transcription": {
    "id": "voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa",
    "accountId": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "status": "COMPLETED",
    "transcriptionConfigurationId": "voice_transcriptionconfiguration_5pe8jw3ahdmsh7zr06yh4d45x1",
    "sourceId": "RExxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "mediaUrl": null,
    "audioStartedAt": "2026-03-10T19:42:16Z",
    "conversationId": "conv_conversation_01k1etx3jbfx88476ccja0889c",
    "participants": [
      { "audioChannelIndex": 1, "type": "CUSTOMER", "address": "+15551234567", "name": "Jane Doe" },
      { "audioChannelIndex": 2, "type": "HUMAN_AGENT", "address": "+15559876543", "name": "Agent Smith" }
    ],
    "duration": 120,
    "resolvedConfiguration": {
      "transcriptionEngine": "deepgram",
      "speechModel": "nova-3",
      "language": "en-US",
      "transcriptionStatusCallback": {
        "url": "https://example.com/transcription/callback",
        "method": "POST",
        "events": null
      },
      "conversationConfigurationId": "conv_configuration_5pe8jw3ahdmsh7zr06yh4d45x1",
      "participantDefaults": [
        { "audioChannelIndex": 1, "type": "CUSTOMER" },
        { "audioChannelIndex": 2, "type": "HUMAN_AGENT" }
      ]
    },
    "createdAt": "2026-04-02T19:25:20Z",
    "updatedAt": "2026-04-02T19:25:20Z",
    "url": "https://voice.twilio.com/v3/Transcriptions/voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa"
  }
}
```