---
"@context": https://schema.org
"@type": TechArticle
"@id": https://www.twilio.com/docs/voice/api/batch-transcription-resource#article
headline: Batch Transcription resource
url: https://www.twilio.com/docs/voice/api/batch-transcription-resource
inLanguage: en
dateModified: 2026-10-02T16:18:32.000Z
author:
  "@type": Organization
  name: Twilio Developer Education Team
publisher:
  "@type": Organization
  name: Twilio
---

# Batch Transcription resource

> \[!NOTE]
>
> 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).

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:

* **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 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, Twilio has no call metadata to infer participants from, so any participant data must come from the `participants` array. `participants` is optional unless you also set `conversationConfigurationId` to store the transcript in a conversation. In that case, `participants` is required so that Twilio can attribute the transcript to the right conversation participants.

## Create a Transcription

> \[!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`.

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

Create a Transcription with a Recording SID

```js
// Download the helper library from https://www.twilio.com/docs/node/install
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

// Find your Account SID at twilio.com/console
// Provision API Keys at twilio.com/console/runtime/api-keys
// and set the environment variables. See http://twil.io/secure
// For local testing, you can use your Account SID and Auth token
const accountSid = process.env.TWILIO_ACCOUNT_SID;
const apiKey = process.env.TWILIO_API_KEY;
const apiSecret = process.env.TWILIO_API_SECRET;
const client = twilio(apiKey, apiSecret, { accountSid: accountSid });

async function createV3Transcriptions() {
  const transcription = await client.voice.v3.transcriptions.create({
    transcriptionConfigurationId:
      "voice_transcriptionconfiguration_5pe8jw3ahdmsh7zr06yh4d45x1",
    sourceId: "RExxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    participants: [
      {
        type: "CUSTOMER",
        address: "+15558675310",
        name: "Dana A.",
        audioChannelIndex: 1,
      },
      {
        type: "HUMAN_AGENT",
        address: "+15017122661",
        name: "Quinn N.",
        audioChannelIndex: 2,
      },
    ],
  });

  console.log(transcription.status);
}

createV3Transcriptions();
```

```python
# Download the helper library from https://www.twilio.com/docs/python/install
import os
from twilio.rest import Client
from twilio.rest.voice.v3 import TranscriptionList

# Find your Account SID at twilio.com/console
# Provision API Keys at twilio.com/console/runtime/api-keys
# and set the environment variables. See http://twil.io/secure
# For local testing, you can use your Account SID and Auth token
api_key = os.environ["TWILIO_API_KEY"]
api_secret = os.environ["TWILIO_API_SECRET"]
account_sid = os.environ["TWILIO_ACCOUNT_SID"]
client = Client(api_key, api_secret, account_sid)

transcription = client.voice.v3.transcriptions.create(
    voice_v3_transcription__create_request_with_source_id=TranscriptionList.VoiceV3TranscriptionCreaterequestwithsourceid(
        {
            "transcriptionConfigurationId": "voice_transcriptionconfiguration_5pe8jw3ahdmsh7zr06yh4d45x1",
            "sourceId": "RExxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
            "participants": [
                TranscriptionList.VoiceV3TranscriptionParticipant(
                    {
                        "type": "CUSTOMER",
                        "address": "+15558675310",
                        "name": "Dana A.",
                        "audioChannelIndex": 1,
                    }
                ),
                TranscriptionList.VoiceV3TranscriptionParticipant(
                    {
                        "type": "HUMAN_AGENT",
                        "address": "+15017122661",
                        "name": "Quinn N.",
                        "audioChannelIndex": 2,
                    }
                ),
            ],
        }
    )
)

print(transcription.status)
```

```csharp
// Install the C# / .NET helper library from twilio.com/docs/csharp/install

using System;
using Twilio;
using Twilio.Rest.Voice.V3;
using System.Threading.Tasks;
using System.Collections.Generic;

class Program {
    public static async Task Main(string[] args) {
        // Find your Account SID at twilio.com/console
        // Provision API Keys at twilio.com/console/runtime/api-keys
        // and set the environment variables. See http://twil.io/secure
        // For local testing, you can use your Account SID and Auth token
        string apiKey = Environment.GetEnvironmentVariable("TWILIO_API_KEY");
        string apiSecret = Environment.GetEnvironmentVariable("TWILIO_API_SECRET");
        string accountSid = Environment.GetEnvironmentVariable("TWILIO_ACCOUNT_SID");

        TwilioClient.Init(apiKey, apiSecret, accountSid);

        var transcription = await TranscriptionResource.CreateAsync(
            voiceV3TranscriptionCreaterequestwithsourceid: new TranscriptionResource
                .VoiceV3TranscriptionCreaterequestwithsourceid.Builder()
                .WithTranscriptionConfigurationId(
                    "voice_transcriptionconfiguration_5pe8jw3ahdmsh7zr06yh4d45x1")
                .WithSourceId("RExxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
                .WithParticipants(new List<TranscriptionResource.VoiceV3TranscriptionParticipant> {
                    new TranscriptionResource.VoiceV3TranscriptionParticipant.Builder()
                        .WithType("CUSTOMER")
                        .WithAddress("+15558675310")
                        .WithName("Dana A.")
                        .WithAudioChannelIndex(1)
                        .Build(),
                    new TranscriptionResource.VoiceV3TranscriptionParticipant.Builder()
                        .WithType("HUMAN_AGENT")
                        .WithAddress("+15017122661")
                        .WithName("Quinn N.")
                        .WithAudioChannelIndex(2)
                        .Build()
                })
                .Build());

        Console.WriteLine(transcription.Status);
    }
}
```

```java
// Install the Java helper library from twilio.com/docs/java/install

import java.util.Arrays;
import java.util.HashMap;
import com.twilio.Twilio;
import com.twilio.rest.voice.v3.Transcription;

public class Example {
    // Find your Account SID at twilio.com/console
    // Provision API Keys at twilio.com/console/runtime/api-keys
    // and set the environment variables. See http://twil.io/secure
    // For local testing, you can use your Account SID and Auth token
    public static final String API_KEY = System.getenv("TWILIO_API_KEY");
    public static final String API_SECRET = System.getenv("TWILIO_API_SECRET");
    public static final String ACCOUNT_SID = System.getenv("TWILIO_ACCOUNT_SID");

    public static void main(String[] args) {
        Twilio.init(API_KEY, API_SECRET, ACCOUNT_SID);

        Transcription.VoiceV3TranscriptionParticipant voiceV3TranscriptionParticipant1 =
            new Transcription.VoiceV3TranscriptionParticipant();
        voiceV3TranscriptionParticipant1.setType("CUSTOMER");
        voiceV3TranscriptionParticipant1.setAddress("+15558675310");
        voiceV3TranscriptionParticipant1.setName("Dana A.");
        voiceV3TranscriptionParticipant1.setAudioChannelIndex(1);

        Transcription.VoiceV3TranscriptionParticipant voiceV3TranscriptionParticipant2 =
            new Transcription.VoiceV3TranscriptionParticipant();
        voiceV3TranscriptionParticipant2.setType("HUMAN_AGENT");
        voiceV3TranscriptionParticipant2.setAddress("+15017122661");
        voiceV3TranscriptionParticipant2.setName("Quinn N.");
        voiceV3TranscriptionParticipant2.setAudioChannelIndex(2);

        Transcription.VoiceV3TranscriptionCreaterequestwithsourceid voiceV3TranscriptionCreaterequestwithsourceid =
            new Transcription.VoiceV3TranscriptionCreaterequestwithsourceid();
        voiceV3TranscriptionCreaterequestwithsourceid.setTranscriptionConfigurationId(
            "voice_transcriptionconfiguration_5pe8jw3ahdmsh7zr06yh4d45x1");
        voiceV3TranscriptionCreaterequestwithsourceid.setSourceId("RExxxxxxxxxxxxxxxxxxxxxxxxxxxxx");
        voiceV3TranscriptionCreaterequestwithsourceid.setParticipants(
            Arrays.asList(voiceV3TranscriptionParticipant1, voiceV3TranscriptionParticipant2));

        Transcription transcription = Transcription.creator(voiceV3TranscriptionCreaterequestwithsourceid).create();

        System.out.println(transcription.getStatus());
    }
}
```

```go
// Download the helper library from https://www.twilio.com/docs/go/install
package main

import (
	"fmt"
	"github.com/twilio/twilio-go"
	voice "github.com/twilio/twilio-go/rest/voice/v3"
	"os"
)

func main() {
	// Find your Account SID at twilio.com/console
	// Provision API Keys at twilio.com/console/runtime/api-keys
	// and set the environment variables. See http://twil.io/secure
	// For local testing, you can use your Account SID and Auth token
	accountSid := os.Getenv("TWILIO_ACCOUNT_SID")
	apiKey := os.Getenv("TWILIO_API_KEY")
	apiSecret := os.Getenv("TWILIO_API_SECRET")
	client := twilio.NewRestClientWithParams(twilio.ClientParams{
		Username:   apiKey,
		Password:   apiSecret,
		AccountSid: accountSid,
	})

	params := &voice.CreateV3TranscriptionsParams{}
	params.SetVoiceV3TranscriptionCreaterequestwithsourceid(voice.VoiceV3TranscriptionCreaterequestwithsourceid{
		TranscriptionConfigurationId: "voice_transcriptionconfiguration_5pe8jw3ahdmsh7zr06yh4d45x1",
		SourceId:                     "RExxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
		Participants: []voice.VoiceV3TranscriptionParticipant{
			voice.VoiceV3TranscriptionParticipant{
				Type:              "CUSTOMER",
				Address:           "+15558675310",
				Name:              "Dana A.",
				AudioChannelIndex: 1,
			},
			voice.VoiceV3TranscriptionParticipant{
				Type:              "HUMAN_AGENT",
				Address:           "+15017122661",
				Name:              "Quinn N.",
				AudioChannelIndex: 2,
			},
		},
	})

	resp, err := client.VoiceV3.CreateV3Transcriptions(params)
	if err != nil {
		fmt.Println(err.Error())
		os.Exit(1)
	} else {
		fmt.Println(resp.Status)
	}
}
```

```php
<?php

// Update the path below to your autoload.php,
// see https://getcomposer.org/doc/01-basic-usage.md
require_once "/path/to/vendor/autoload.php";

use Twilio\Rest\Client;
use Twilio\Rest\Voice\V3\TranscriptionModels;

// Find your Account SID at twilio.com/console
// Provision API Keys at twilio.com/console/runtime/api-keys
// and set the environment variables. See http://twil.io/secure
// For local testing, you can use your Account SID and Auth token
$apiKey = $_ENV["TWILIO_API_KEY"];
$apiSecret = $_ENV["TWILIO_API_SECRET"];
$sid = $_ENV["TWILIO_ACCOUNT_SID"];
$twilio = new Client($apiKey, $apiSecret, $sid);

$transcription = $twilio->voice->v3->transcriptions->create(
    TranscriptionModels::createVoiceV3TranscriptionCreaterequestwithsourceid([
        "transcriptionConfigurationId" =>
            "voice_transcriptionconfiguration_5pe8jw3ahdmsh7zr06yh4d45x1",
        "sourceId" => "RExxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "participants" => [
            TranscriptionModels::createVoiceV3TranscriptionParticipant([
                "type" => "CUSTOMER",
                "address" => "+15558675310",
                "name" => "Dana A.",
                "audioChannelIndex" => 1,
            ]),
            TranscriptionModels::createVoiceV3TranscriptionParticipant([
                "type" => "HUMAN_AGENT",
                "address" => "+15017122661",
                "name" => "Quinn N.",
                "audioChannelIndex" => 2,
            ]),
        ],
    ]),
);

print $transcription->status;
```

```ruby
# Download the helper library from https://www.twilio.com/docs/ruby/install
require 'twilio-ruby'

# Find your Account SID at twilio.com/console
# Provision API Keys at twilio.com/console/runtime/api-keys
# and set the environment variables. See http://twil.io/secure
# For local testing, you can use your Account SID and Auth token
api_key = ENV['TWILIO_API_KEY']
api_secret = ENV['TWILIO_API_SECRET']
account_sid = ENV['TWILIO_ACCOUNT_SID']
@client = Twilio::REST::Client.new(api_key, api_secret, account_sid)

transcription = @client
                .voice
                .v3
                .transcriptions
                .create(
                  voice_v3_transcription__create_request_with_source_id: {
                    'transcriptionConfigurationId' => 'voice_transcriptionconfiguration_5pe8jw3ahdmsh7zr06yh4d45x1',
                    'sourceId' => 'RExxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
                    'participants' => [
                      {
                        'type' => 'CUSTOMER',
                        'address' => '+15558675310',
                        'name' => 'Dana A.',
                        'audioChannelIndex' => 1
                      },
                      {
                        'type' => 'HUMAN_AGENT',
                        'address' => '+15017122661',
                        'name' => 'Quinn N.',
                        'audioChannelIndex' => 2
                      }
                    ]
                  }
                )

puts transcription.status
```

```bash
# This endpoint is not currently supported by the Twilio CLI. You can open an issue to request it on https://github.com/twilio/twilio-cli/issues
  # For an alternative low-code solution, check out https://www.twilio.com/docs/openapi/using-twilio-postman-collections
```

```bash
VOICE_V3_TRANSCRIPTION__CREATE_REQUEST_WITH_SOURCE_ID_OBJ=$(cat << EOF
{
  "transcriptionConfigurationId": "voice_transcriptionconfiguration_5pe8jw3ahdmsh7zr06yh4d45x1",
  "sourceId": "RExxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "participants": [
    {
      "type": "CUSTOMER",
      "address": "+15558675310",
      "name": "Dana A.",
      "audioChannelIndex": 1
    },
    {
      "type": "HUMAN_AGENT",
      "address": "+15017122661",
      "name": "Quinn N.",
      "audioChannelIndex": 2
    }
  ]
}
EOF
)
curl -X POST "https://voice.twilio.com/v3/Transcriptions" \
--json "$VOICE_V3_TRANSCRIPTION__CREATE_REQUEST_WITH_SOURCE_ID_OBJ" \
-u $TWILIO_API_KEY:$TWILIO_API_SECRET
```

```json
{
  "status": "PENDING",
  "statusUrl": "https://voice.twilio.com/v3/Transcriptions/voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa",
  "transcription": {
    "id": "voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa",
    "accountId": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "status": "PENDING",
    "transcriptionConfigurationId": "voice_transcriptionconfiguration_5pe8jw3ahdmsh7zr06yh4d45x1",
    "sourceId": "RExxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "mediaUrl": null,
    "audioStartedAt": "2026-03-10T19:42:16Z",
    "conversationId": null,
    "participants": [
      { "audioChannelIndex": 1, "type": "CUSTOMER", "address": "+15558675310", "name": "Dana A." },
      { "audioChannelIndex": 2, "type": "HUMAN_AGENT", "address": "+15017122661", "name": "Quinn N." }
    ],
    "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`.

If you also set `conversationConfigurationId`, you must include `participants`. See [Specify participant information](#specify-participant-information).

```bash
curl -X POST https://voice.twilio.com/v3/Transcriptions \
  -u "$TWILIO_API_KEY:$TWILIO_API_SECRET" \
  -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": "+15558675310", "name": "Dana A." },
      { "audioChannelIndex": 2, "type": "HUMAN_AGENT", "address": "+15017122661", "name": "Quinn N." }
    ]
  }'
```

```json
{
  "status": "PENDING",
  "statusUrl": "https://voice.twilio.com/v3/Transcriptions/voice_transcription_4abcde1234567890abcde12345",
  "transcription": {
    "id": "voice_transcription_4abcde1234567890abcde12345",
    "accountId": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "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": "+15558675310", "name": "Dana A." },
      { "audioChannelIndex": 2, "type": "HUMAN_AGENT", "address": "+15017122661", "name": "Quinn N." }
    ],
    "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"
  }
}
```

## Receive transcription results with a webhook

To receive transcription results to a webhook, set the `transcriptionStatusCallback` value in your transcription configuration to a URL that you control where you can receive `POST` requests. When transcription processing completes, Twilio sends a `POST` request with the full transcript to your callback URL.

> \[!NOTE]
>
> A transcription is marked `completed` when processing succeeds, regardless of webhook delivery status. If webhook delivery ultimately fails and you haven't set a `conversationConfigurationId`, the transcript content is unrecoverable. For critical workloads, set a `conversationConfigurationId` on your Transcription Configuration as a backup. This backup stores results in a conversation configuration even if webhook delivery fails.

### Webhook payload reference

The webhook request body contains the complete transcription result. Properties with a `null` value are omitted from the payload, so fields such as `mediaUrl` and `conversationId` don't appear in every webhook.

The following table describes the top-level properties:

| Property                       | Type           | Description                                                                                                                                                                               |
| :----------------------------- | :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                           | string         | The ID of the transcription job. Begins with `voice_transcription_`.                                                                                                                      |
| `accountId`                    | string         | Your Twilio Account SID.                                                                                                                                                                  |
| `status`                       | string         | The status of the transcription. Either `completed` or `failed`.                                                                                                                          |
| `transcriptionConfigurationId` | string         | The ID of the Transcription Configuration used for this transcription.                                                                                                                    |
| `sourceId`                     | string or null | The SID of the Twilio Recording, if you're transcribing a recording.                                                                                                                      |
| `mediaUrl`                     | string or null | The URL of the external audio file, if you're transcribing third-party media.                                                                                                             |
| `conversationId`               | string or null | The ID of the conversation, if Twilio stored the transcript. Use it to [retrieve the transcript from the conversation](#retrieve-a-stored-transcript). Omitted for webhook-only delivery. |
| `audioStartedAt`               | datetime       | The start time of the audio recording, in ISO 8601 format.                                                                                                                                |
| `duration`                     | integer        | The audio duration, in seconds.                                                                                                                                                           |
| `participants`                 | array          | An array of resolved participants, each with a type, address, name, and channel index.                                                                                                    |
| `resolvedConfiguration`        | object         | The engine, model, language, and settings applied to this transcription.                                                                                                                  |
| `sentences`                    | array          | The full transcript content. See the following sentence properties.                                                                                                                       |
| `error`                        | object or null | Present when `status` is `failed`. See the following error properties.                                                                                                                    |
| `createdAt`                    | datetime       | The date and time the transcription job was created, in ISO 8601 format.                                                                                                                  |
| `updatedAt`                    | datetime       | The date and time the status was last updated, in ISO 8601 format.                                                                                                                        |

The following table describes the properties of each object in the `sentences` array:

| Property            | Type            | Description                                                                                            |
| :------------------ | :-------------- | :----------------------------------------------------------------------------------------------------- |
| `audioChannelIndex` | integer         | The audio channel. For dual-channel audio, channel `1` is typically the customer and `2` the agent.    |
| `sentenceIndex`     | integer         | The position within the transcript, starting at `1`.                                                   |
| `participantIndex`  | integer or null | The index into the `participants` array that identifies the speaker.                                   |
| `languageCode`      | string or null  | The detected language for this sentence, in BCP-47 format. Present when you set `"language": "multi"`. |
| `startTimeSeconds`  | number          | When the sentence begins, in seconds from the audio start.                                             |
| `endTimeSeconds`    | number          | When the sentence ends, in seconds from the audio start.                                               |
| `text`              | string          | The transcribed text.                                                                                  |
| `confidence`        | number          | The confidence score, from `0.0` to `1.0`.                                                             |
| `words`             | array           | Word-level detail. See the following word properties.                                                  |

The following table describes the properties of each object in the `words` array:

| Property           | Type   | Description                                            |
| :----------------- | :----- | :----------------------------------------------------- |
| `word`             | string | The transcribed word.                                  |
| `startTimeSeconds` | number | When the word begins, in seconds from the audio start. |
| `endTimeSeconds`   | number | When the word ends, in seconds from the audio start.   |

The following table describes the `error` object, which is present only when `status` is `failed`:

| Property  | Type    | Description                             |
| :-------- | :------ | :-------------------------------------- |
| `level`   | string  | The severity of the error.              |
| `message` | string  | A description of what went wrong.       |
| `code`    | integer | The error code identifying the failure. |

### Example webhook payload

The following example shows a webhook payload for a completed transcription:

```json
{
  "id": "voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa",
  "accountId": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "status": "completed",
  "transcriptionConfigurationId": "voice_transcriptionconfiguration_5pe8jw3ahdmsh7zr06yh4d45x1",
  "sourceId": "RExxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "audioStartedAt": "2026-06-15T19:42:16Z",
  "duration": 245,
  "participants": [
    {
      "type": "CUSTOMER",
      "address": "+18005550100",
      "name": "Dana A.",
      "audioChannelIndex": 1
    },
    {
      "type": "HUMAN_AGENT",
      "address": "+18005550101",
      "name": "Quinn N.",
      "audioChannelIndex": 2
    }
  ],
  "resolvedConfiguration": {
    "transcriptionEngine": "deepgram",
    "speechModel": "nova-3",
    "language": "en-US",
    "transcriptionStatusCallback": {
      "url": "https://example.com/transcription-webhook",
      "method": "POST"
    }
  },
  "sentences": [
    {
      "audioChannelIndex": 1,
      "sentenceIndex": 1,
      "participantIndex": 0,
      "startTimeSeconds": 0.08,
      "endTimeSeconds": 3.2,
      "text": "Hi, I'm calling about my recent order.",
      "confidence": 0.97,
      "words": [
        { "word": "Hi,", "startTimeSeconds": 0.08, "endTimeSeconds": 0.3 },
        { "word": "I'm", "startTimeSeconds": 0.48, "endTimeSeconds": 0.72 },
        { "word": "calling", "startTimeSeconds": 0.72, "endTimeSeconds": 1.12 },
        { "word": "about", "startTimeSeconds": 1.12, "endTimeSeconds": 1.36 },
        { "word": "my", "startTimeSeconds": 1.36, "endTimeSeconds": 1.52 },
        { "word": "recent", "startTimeSeconds": 1.52, "endTimeSeconds": 1.92 },
        { "word": "order.", "startTimeSeconds": 1.92, "endTimeSeconds": 3.2 }
      ]
    }
  ],
  "createdAt": "2026-06-15T19:42:16Z",
  "updatedAt": "2026-06-15T19:42:45Z"
}
```

The following example shows a webhook payload for a failed transcription, which includes the `error` object instead of `sentences`:

```json
{
  "id": "voice_transcription_4abcde1234567890abcde12345",
  "accountId": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "status": "failed",
  "transcriptionConfigurationId": "voice_transcriptionconfiguration_5pe8jw3ahdmsh7zr06yh4d45x1",
  "mediaUrl": "https://example.com/audio/recording.wav",
  "audioStartedAt": "2026-06-15T18:10:05Z",
  "participants": [],
  "resolvedConfiguration": {
    "transcriptionEngine": "deepgram",
    "speechModel": "nova-3",
    "language": "en-US",
    "transcriptionStatusCallback": {
      "url": "https://example.com/transcription-webhook",
      "method": "POST"
    }
  },
  "error": {
    "code": 95111,
    "message": "Failed to download media file: unauthorized",
    "level": "ERROR"
  },
  "createdAt": "2026-06-15T18:10:05Z",
  "updatedAt": "2026-06-15T18:10:09Z"
}
```

### Verify webhook requests

Before your application acts on a webhook, verify that Twilio sent it. Twilio signs each request with an `X-Twilio-Signature` header that you can validate using the server-side Twilio helper libraries. For the steps and code samples, see [Webhooks security](/docs/usage/webhooks/webhooks-security#understand-parameters-in-signature-validation).

### Webhook retry behavior

If your endpoint is unavailable or returns an error, Twilio retries the request based on the retry count and retry policy configured for your account. To control how many times Twilio retries, which failures it retries on, and the total timeout, see [Webhooks connection overrides](/docs/usage/webhooks/webhooks-connection-overrides).

If Twilio can't deliver the status callback, it logs one of the following warnings to the [Debugger](/docs/usage/troubleshooting/debugging-your-application). The transcription itself isn't affected in any of these cases.

| Error code                      | Meaning                                                                     |
| :------------------------------ | :-------------------------------------------------------------------------- |
| [17580](/docs/api/errors/17580) | Your endpoint returned an HTTP error response.                              |
| [17581](/docs/api/errors/17581) | Your endpoint didn't respond before the timeout elapsed.                    |
| [17582](/docs/api/errors/17582) | Twilio couldn't connect to your endpoint after all retries.                 |
| [17583](/docs/api/errors/17583) | Your endpoint's response body exceeded the maximum permitted size.          |
| [17584](/docs/api/errors/17584) | The callback URL exceeded the maximum number of HTTP redirects.             |
| [17585](/docs/api/errors/17585) | The callback URL isn't a valid HTTP or HTTPS URL, so Twilio didn't send it. |

### Webhook payload size limit

Twilio delivers a status callback only when the serialized webhook payload is 1 MB or smaller. If a completed transcription produces a payload larger than 1 MB, Twilio skips the status callback and logs warning [17564](/docs/api/errors/17564) to the Debugger.

The transcription itself isn't affected: Twilio still marks it `completed`. The transcript content, however, is only retrievable if you set a `conversationConfigurationId`. [Fetch a Transcription](#fetch-a-transcription) returns the transcription's status and metadata, not the transcript text.

Long recordings are the most common cause, because the per-sentence text, timing, and word-level confidence scores in the payload all count toward the limit.

To keep long transcripts retrievable, set a `conversationConfigurationId` on your Transcription Configuration. Twilio then stores the transcript in [Conversation Orchestrator](/docs/conversations/orchestrator), whatever the payload size. See [Retrieve a stored transcript](#retrieve-a-stored-transcript) for how to create the configuration and read the transcript back.

> \[!WARNING]
>
> Twilio retains transcription results only when you set a `conversationConfigurationId`. If you rely on the status callback alone and the payload exceeds 1 MB, the transcript content is unrecoverable.

### Retrieve a stored transcript

When your Transcription Configuration has a `conversationConfigurationId`, Twilio stores each transcript in [Conversation Orchestrator](/docs/conversations/orchestrator) as a [communication](/docs/conversations/orchestrator/concepts/core) on a conversation. This gives you a durable copy that doesn't depend on webhook delivery.

**1. Create a conversation configuration.** You need its ID before you can store transcripts. Create one with the [Conversation Orchestrator quickstart](/docs/conversations/orchestrator/quickstart), the [Conversations API](/docs/api/conversations/v2/configuration/create-configuration), or the Twilio Console. Then set it as `conversationConfigurationId` on your Transcription Configuration.

**2. Get the conversation ID.** Twilio returns `conversationId` on the transcription, in both the [status callback payload](#webhook-payload-reference) and the [Fetch a Transcription](#fetch-a-transcription) response.

**3. Read the transcript.** Send a `GET` to the Communications endpoint for that conversation. The `content` property of each communication holds the speech-to-text transcript.

Retrieve the transcript from a conversation

```js
// Download the helper library from https://www.twilio.com/docs/node/install
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

// Find your Account SID at twilio.com/console
// Provision API Keys at twilio.com/console/runtime/api-keys
// and set the environment variables. See http://twil.io/secure
// For local testing, you can use your Account SID and Auth token
const accountSid = process.env.TWILIO_ACCOUNT_SID;
const apiKey = process.env.TWILIO_API_KEY;
const apiSecret = process.env.TWILIO_API_SECRET;
const client = twilio(apiKey, apiSecret, { accountSid: accountSid });

async function listCommunicationByConversation() {
  const communications = await client.conversations.v2
    .communications("conv_conversation_01k1etx3jbfx88476ccja0889c")
    .list({ limit: 20 });

  communications.forEach((c) => console.log(c.id));
}

listCommunicationByConversation();
```

```python
# Download the helper library from https://www.twilio.com/docs/python/install
import os
from twilio.rest import Client

# Find your Account SID at twilio.com/console
# Provision API Keys at twilio.com/console/runtime/api-keys
# and set the environment variables. See http://twil.io/secure
# For local testing, you can use your Account SID and Auth token
api_key = os.environ["TWILIO_API_KEY"]
api_secret = os.environ["TWILIO_API_SECRET"]
account_sid = os.environ["TWILIO_ACCOUNT_SID"]
client = Client(api_key, api_secret, account_sid)

communications = client.conversations.v2.communications(
    "conv_conversation_01k1etx3jbfx88476ccja0889c"
).list(limit=20)

for record in communications:
    print(record.id)
```

```csharp
// Install the C# / .NET helper library from twilio.com/docs/csharp/install

using System;
using Twilio;
using Twilio.Rest.Conversations.V2;
using System.Threading.Tasks;

class Program {
    public static async Task Main(string[] args) {
        // Find your Account SID at twilio.com/console
        // Provision API Keys at twilio.com/console/runtime/api-keys
        // and set the environment variables. See http://twil.io/secure
        // For local testing, you can use your Account SID and Auth token
        string apiKey = Environment.GetEnvironmentVariable("TWILIO_API_KEY");
        string apiSecret = Environment.GetEnvironmentVariable("TWILIO_API_SECRET");
        string accountSid = Environment.GetEnvironmentVariable("TWILIO_ACCOUNT_SID");

        TwilioClient.Init(apiKey, apiSecret, accountSid);

        var communications = await CommunicationResource.ReadAsync(
            pathConversationId: "conv_conversation_01k1etx3jbfx88476ccja0889c", limit: 20);

        foreach (var record in communications) {
            Console.WriteLine(record.Id);
        }
    }
}
```

```java
// Install the Java helper library from twilio.com/docs/java/install

import com.twilio.Twilio;
import com.twilio.rest.conversations.v2.Communication;
import com.twilio.base.ResourceSet;

public class Example {
    // Find your Account SID at twilio.com/console
    // Provision API Keys at twilio.com/console/runtime/api-keys
    // and set the environment variables. See http://twil.io/secure
    // For local testing, you can use your Account SID and Auth token
    public static final String API_KEY = System.getenv("TWILIO_API_KEY");
    public static final String API_SECRET = System.getenv("TWILIO_API_SECRET");
    public static final String ACCOUNT_SID = System.getenv("TWILIO_ACCOUNT_SID");

    public static void main(String[] args) {
        Twilio.init(API_KEY, API_SECRET, ACCOUNT_SID);
        ResourceSet<Communication.ListCommunicationResponse> communications =
            Communication.reader("conv_conversation_01k1etx3jbfx88476ccja0889c").limit(20).read();

        for (Communication.ListCommunicationResponse communication : communications) {
            System.out.println(communication.getId());
        }
    }
}
```

```go
// Download the helper library from https://www.twilio.com/docs/go/install
package main

import (
	"fmt"
	"github.com/twilio/twilio-go"
	conversations "github.com/twilio/twilio-go/rest/conversations/v2"
	"os"
)

func main() {
	// Find your Account SID at twilio.com/console
	// Provision API Keys at twilio.com/console/runtime/api-keys
	// and set the environment variables. See http://twil.io/secure
	// For local testing, you can use your Account SID and Auth token
	accountSid := os.Getenv("TWILIO_ACCOUNT_SID")
	apiKey := os.Getenv("TWILIO_API_KEY")
	apiSecret := os.Getenv("TWILIO_API_SECRET")
	client := twilio.NewRestClientWithParams(twilio.ClientParams{
		Username:   apiKey,
		Password:   apiSecret,
		AccountSid: accountSid,
	})

	params := &conversations.ListCommunicationByConversationParams{}
	params.SetLimit(20)

	resp, err := client.ConversationsV2.ListCommunicationByConversation("conv_conversation_01k1etx3jbfx88476ccja0889c",
		params)
	if err != nil {
		fmt.Println(err.Error())
		os.Exit(1)
	} else {
		for record := range resp {
			fmt.Println(resp[record].Id)
		}
	}
}
```

```php
<?php

// Update the path below to your autoload.php,
// see https://getcomposer.org/doc/01-basic-usage.md
require_once "/path/to/vendor/autoload.php";

use Twilio\Rest\Client;

// Find your Account SID at twilio.com/console
// Provision API Keys at twilio.com/console/runtime/api-keys
// and set the environment variables. See http://twil.io/secure
// For local testing, you can use your Account SID and Auth token
$apiKey = $_ENV["TWILIO_API_KEY"];
$apiSecret = $_ENV["TWILIO_API_SECRET"];
$sid = $_ENV["TWILIO_ACCOUNT_SID"];
$twilio = new Client($apiKey, $apiSecret, $sid);

$communications = $twilio->conversations->v2->communications->read(
    "conv_conversation_01k1etx3jbfx88476ccja0889c",
    [],
    20,
);

foreach ($communications as $record) {
    print $record->id;
}
```

```ruby
# Download the helper library from https://www.twilio.com/docs/ruby/install
require 'twilio-ruby'

# Find your Account SID at twilio.com/console
# Provision API Keys at twilio.com/console/runtime/api-keys
# and set the environment variables. See http://twil.io/secure
# For local testing, you can use your Account SID and Auth token
api_key = ENV['TWILIO_API_KEY']
api_secret = ENV['TWILIO_API_SECRET']
account_sid = ENV['TWILIO_ACCOUNT_SID']
@client = Twilio::REST::Client.new(api_key, api_secret, account_sid)

communications = @client
                 .conversations
                 .v2
                 .communications('conv_conversation_01k1etx3jbfx88476ccja0889c')
                 .list(limit: 20)

communications.each do |record|
   puts record.id
end
```

```bash
# Install the twilio-cli from https://twil.io/cli

twilio api:conversations:v2:conversations:communications:list \
   --conversation-id conv_conversation_01k1etx3jbfx88476ccja0889c
```

```bash
curl -X GET "https://conversations.twilio.com/v2/Conversations/conv_conversation_01k1etx3jbfx88476ccja0889c/Communications?PageSize=20" \
-u $TWILIO_API_KEY:$TWILIO_API_SECRET
```

For the full object model, see [Core concepts](/docs/conversations/orchestrator/concepts/core).

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

Fetch a Transcription

```js
// Download the helper library from https://www.twilio.com/docs/node/install
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

// Find your Account SID at twilio.com/console
// Provision API Keys at twilio.com/console/runtime/api-keys
// and set the environment variables. See http://twil.io/secure
// For local testing, you can use your Account SID and Auth token
const accountSid = process.env.TWILIO_ACCOUNT_SID;
const apiKey = process.env.TWILIO_API_KEY;
const apiSecret = process.env.TWILIO_API_SECRET;
const client = twilio(apiKey, apiSecret, { accountSid: accountSid });

async function fetchTranscription() {
  const transcription = await client.voice.v3
    .transcriptions("voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa")
    .fetch();

  console.log(transcription.operationId);
}

fetchTranscription();
```

```python
# Download the helper library from https://www.twilio.com/docs/python/install
import os
from twilio.rest import Client

# Find your Account SID at twilio.com/console
# Provision API Keys at twilio.com/console/runtime/api-keys
# and set the environment variables. See http://twil.io/secure
# For local testing, you can use your Account SID and Auth token
api_key = os.environ["TWILIO_API_KEY"]
api_secret = os.environ["TWILIO_API_SECRET"]
account_sid = os.environ["TWILIO_ACCOUNT_SID"]
client = Client(api_key, api_secret, account_sid)

transcription = client.voice.v3.transcriptions(
    "voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa"
).fetch()

print(transcription.operation_id)
```

```csharp
// Install the C# / .NET helper library from twilio.com/docs/csharp/install

using System;
using Twilio;
using Twilio.Rest.Voice.V3;
using System.Threading.Tasks;

class Program {
    public static async Task Main(string[] args) {
        // Find your Account SID at twilio.com/console
        // Provision API Keys at twilio.com/console/runtime/api-keys
        // and set the environment variables. See http://twil.io/secure
        // For local testing, you can use your Account SID and Auth token
        string apiKey = Environment.GetEnvironmentVariable("TWILIO_API_KEY");
        string apiSecret = Environment.GetEnvironmentVariable("TWILIO_API_SECRET");
        string accountSid = Environment.GetEnvironmentVariable("TWILIO_ACCOUNT_SID");

        TwilioClient.Init(apiKey, apiSecret, accountSid);

        var transcription = await TranscriptionResource.FetchAsync(
            pathTranscriptionId: "voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa");

        Console.WriteLine(transcription.OperationId);
    }
}
```

```java
// Install the Java helper library from twilio.com/docs/java/install

import com.twilio.Twilio;
import com.twilio.rest.voice.v3.Transcription;

public class Example {
    // Find your Account SID at twilio.com/console
    // Provision API Keys at twilio.com/console/runtime/api-keys
    // and set the environment variables. See http://twil.io/secure
    // For local testing, you can use your Account SID and Auth token
    public static final String API_KEY = System.getenv("TWILIO_API_KEY");
    public static final String API_SECRET = System.getenv("TWILIO_API_SECRET");
    public static final String ACCOUNT_SID = System.getenv("TWILIO_ACCOUNT_SID");

    public static void main(String[] args) {
        Twilio.init(API_KEY, API_SECRET, ACCOUNT_SID);
        Transcription transcription = Transcription.fetcher("voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa").fetch();

        System.out.println(transcription.getOperationId());
    }
}
```

```go
// Download the helper library from https://www.twilio.com/docs/go/install
package main

import (
	"fmt"
	"github.com/twilio/twilio-go"
	"os"
)

func main() {
	// Find your Account SID at twilio.com/console
	// Provision API Keys at twilio.com/console/runtime/api-keys
	// and set the environment variables. See http://twil.io/secure
	// For local testing, you can use your Account SID and Auth token
	accountSid := os.Getenv("TWILIO_ACCOUNT_SID")
	apiKey := os.Getenv("TWILIO_API_KEY")
	apiSecret := os.Getenv("TWILIO_API_SECRET")
	client := twilio.NewRestClientWithParams(twilio.ClientParams{
		Username:   apiKey,
		Password:   apiSecret,
		AccountSid: accountSid,
	})

	resp, err := client.VoiceV3.FetchTranscription("voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa")
	if err != nil {
		fmt.Println(err.Error())
		os.Exit(1)
	} else {
		fmt.Println(resp.OperationId)
	}
}
```

```php
<?php

// Update the path below to your autoload.php,
// see https://getcomposer.org/doc/01-basic-usage.md
require_once "/path/to/vendor/autoload.php";

use Twilio\Rest\Client;

// Find your Account SID at twilio.com/console
// Provision API Keys at twilio.com/console/runtime/api-keys
// and set the environment variables. See http://twil.io/secure
// For local testing, you can use your Account SID and Auth token
$apiKey = $_ENV["TWILIO_API_KEY"];
$apiSecret = $_ENV["TWILIO_API_SECRET"];
$sid = $_ENV["TWILIO_ACCOUNT_SID"];
$twilio = new Client($apiKey, $apiSecret, $sid);

$transcription = $twilio->voice->v3
    ->transcriptions("voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa")
    ->fetch();

print $transcription->operationId;
```

```ruby
# Download the helper library from https://www.twilio.com/docs/ruby/install
require 'twilio-ruby'

# Find your Account SID at twilio.com/console
# Provision API Keys at twilio.com/console/runtime/api-keys
# and set the environment variables. See http://twil.io/secure
# For local testing, you can use your Account SID and Auth token
api_key = ENV['TWILIO_API_KEY']
api_secret = ENV['TWILIO_API_SECRET']
account_sid = ENV['TWILIO_ACCOUNT_SID']
@client = Twilio::REST::Client.new(api_key, api_secret, account_sid)

transcription = @client
                .voice
                .v3
                .transcriptions('voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa')
                .fetch

puts transcription.operation_id
```

```bash
# Install the twilio-cli from https://twil.io/cli

twilio api:voice:v3:transcriptions:fetch \
   --transcription-id voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa
```

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

```json
{
  "operationId": "voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa",
  "status": "COMPLETED",
  "statusUrl": "https://voice.twilio.com/v3/Transcriptions/voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa",
  "transcription": {
    "id": "voice_transcription_7n7hnd7sf68yfv5re42nvvz7aa",
    "accountId": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "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": "+18005550100", "name": "Dana A." },
      { "audioChannelIndex": 2, "type": "HUMAN_AGENT", "address": "+18005550101", "name": "Quinn N." }
    ],
    "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"
  }
}
```

## List Transcriptions

Retrieve a paginated list of the account's transcriptions, newest first. All filters are optional; if you provide more than one, only transcriptions that match every filter are returned.

### Query parameters

| Parameter       | Type    | Description                                                                                                                             |
| --------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `status`        | string  | Only return transcriptions in this status: `PENDING`, `RUNNING`, `COMPLETED`, or `FAILED`.                                              |
| `sourceId`      | string  | Only return transcriptions for this Recording SID (`RE` followed by 32 lowercase hexadecimal characters).                               |
| `languageCode`  | string  | Only return transcriptions whose resolved language matches this value exactly. Case sensitive, for example `en-US`.                     |
| `createdAfter`  | string  | Only return transcriptions created at or after this time (inclusive). ISO 8601.                                                         |
| `createdBefore` | string  | Only return transcriptions created strictly before this time (exclusive). ISO 8601.                                                     |
| `pageSize`      | integer | Number of results per page, from 1 to 100. Defaults to 50.                                                                              |
| `pageToken`     | string  | Opaque cursor from a previous response's `meta.nextToken` or `meta.previousToken`. Only valid for the same filter set that produced it. |

List Transcriptions

```js
// Download the helper library from https://www.twilio.com/docs/node/install
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

// Find your Account SID at twilio.com/console
// Provision API Keys at twilio.com/console/runtime/api-keys
// and set the environment variables. See http://twil.io/secure
// For local testing, you can use your Account SID and Auth token
const accountSid = process.env.TWILIO_ACCOUNT_SID;
const apiKey = process.env.TWILIO_API_KEY;
const apiSecret = process.env.TWILIO_API_SECRET;
const client = twilio(apiKey, apiSecret, { accountSid: accountSid });

async function listV3Transcriptions() {
  const transcriptions = await client.voice.v3.transcriptions.list({
    status: "COMPLETED",
    limit: 20,
  });

  transcriptions.forEach((t) => console.log(t.id));
}

listV3Transcriptions();
```

```python
# Download the helper library from https://www.twilio.com/docs/python/install
import os
from twilio.rest import Client

# Find your Account SID at twilio.com/console
# Provision API Keys at twilio.com/console/runtime/api-keys
# and set the environment variables. See http://twil.io/secure
# For local testing, you can use your Account SID and Auth token
api_key = os.environ["TWILIO_API_KEY"]
api_secret = os.environ["TWILIO_API_SECRET"]
account_sid = os.environ["TWILIO_ACCOUNT_SID"]
client = Client(api_key, api_secret, account_sid)

transcriptions = client.voice.v3.transcriptions.list(
    status="COMPLETED", limit=20
)

for record in transcriptions:
    print(record.id)
```

```csharp
// Install the C# / .NET helper library from twilio.com/docs/csharp/install

using System;
using Twilio;
using Twilio.Rest.Voice.V3;
using System.Threading.Tasks;

class Program {
    public static async Task Main(string[] args) {
        // Find your Account SID at twilio.com/console
        // Provision API Keys at twilio.com/console/runtime/api-keys
        // and set the environment variables. See http://twil.io/secure
        // For local testing, you can use your Account SID and Auth token
        string apiKey = Environment.GetEnvironmentVariable("TWILIO_API_KEY");
        string apiSecret = Environment.GetEnvironmentVariable("TWILIO_API_SECRET");
        string accountSid = Environment.GetEnvironmentVariable("TWILIO_ACCOUNT_SID");

        TwilioClient.Init(apiKey, apiSecret, accountSid);

        var transcriptions = await TranscriptionResource.ReadAsync(
            status: TranscriptionResource.StatusEnum.Completed, limit: 20);

        foreach (var record in transcriptions) {
            Console.WriteLine(record.Id);
        }
    }
}
```

```java
// Install the Java helper library from twilio.com/docs/java/install

import com.twilio.Twilio;
import com.twilio.rest.voice.v3.Transcription;
import com.twilio.base.ResourceSet;

public class Example {
    // Find your Account SID at twilio.com/console
    // Provision API Keys at twilio.com/console/runtime/api-keys
    // and set the environment variables. See http://twil.io/secure
    // For local testing, you can use your Account SID and Auth token
    public static final String API_KEY = System.getenv("TWILIO_API_KEY");
    public static final String API_SECRET = System.getenv("TWILIO_API_SECRET");
    public static final String ACCOUNT_SID = System.getenv("TWILIO_ACCOUNT_SID");

    public static void main(String[] args) {
        Twilio.init(API_KEY, API_SECRET, ACCOUNT_SID);
        ResourceSet<Transcription> transcriptions =
            Transcription.reader().setStatus(Transcription.Status.COMPLETED).limit(20).read();

        for (Transcription record : transcriptions) {
            System.out.println(record.getId());
        }
    }
}
```

```go
// Download the helper library from https://www.twilio.com/docs/go/install
package main

import (
	"fmt"
	"github.com/twilio/twilio-go"
	voice "github.com/twilio/twilio-go/rest/voice/v3"
	"os"
)

func main() {
	// Find your Account SID at twilio.com/console
	// Provision API Keys at twilio.com/console/runtime/api-keys
	// and set the environment variables. See http://twil.io/secure
	// For local testing, you can use your Account SID and Auth token
	accountSid := os.Getenv("TWILIO_ACCOUNT_SID")
	apiKey := os.Getenv("TWILIO_API_KEY")
	apiSecret := os.Getenv("TWILIO_API_SECRET")
	client := twilio.NewRestClientWithParams(twilio.ClientParams{
		Username:   apiKey,
		Password:   apiSecret,
		AccountSid: accountSid,
	})

	params := &voice.ListV3TranscriptionsParams{}
	params.SetStatus("COMPLETED")
	params.SetLimit(20)

	resp, err := client.VoiceV3.ListV3Transcriptions(params)
	if err != nil {
		fmt.Println(err.Error())
		os.Exit(1)
	} else {
		for record := range resp {
			fmt.Println(resp[record].Id)
		}
	}
}
```

```php
<?php

// Update the path below to your autoload.php,
// see https://getcomposer.org/doc/01-basic-usage.md
require_once "/path/to/vendor/autoload.php";

use Twilio\Rest\Client;

// Find your Account SID at twilio.com/console
// Provision API Keys at twilio.com/console/runtime/api-keys
// and set the environment variables. See http://twil.io/secure
// For local testing, you can use your Account SID and Auth token
$apiKey = $_ENV["TWILIO_API_KEY"];
$apiSecret = $_ENV["TWILIO_API_SECRET"];
$sid = $_ENV["TWILIO_ACCOUNT_SID"];
$twilio = new Client($apiKey, $apiSecret, $sid);

$transcriptions = $twilio->voice->v3->transcriptions->read(
    ["status" => "COMPLETED"],
    20,
);

foreach ($transcriptions as $record) {
    print $record->id;
}
```

```ruby
# Download the helper library from https://www.twilio.com/docs/ruby/install
require 'twilio-ruby'

# Find your Account SID at twilio.com/console
# Provision API Keys at twilio.com/console/runtime/api-keys
# and set the environment variables. See http://twil.io/secure
# For local testing, you can use your Account SID and Auth token
api_key = ENV['TWILIO_API_KEY']
api_secret = ENV['TWILIO_API_SECRET']
account_sid = ENV['TWILIO_ACCOUNT_SID']
@client = Twilio::REST::Client.new(api_key, api_secret, account_sid)

transcriptions = @client
                 .voice
                 .v3
                 .transcriptions
                 .list(
                   status: 'COMPLETED',
                   limit: 20
                 )

transcriptions.each do |record|
   puts record.id
end
```

```bash
# Install the twilio-cli from https://twil.io/cli

twilio api:voice:v3:transcriptions:list \
   --status COMPLETED
```

```bash
curl -X GET "https://voice.twilio.com/v3/Transcriptions?status=COMPLETED&PageSize=20" \
-u $TWILIO_API_KEY:$TWILIO_API_SECRET
```

```json
{
  "transcriptions": [
    {
      "id": "voice_transcription_72c3dv9f7r97j85angc18z4bjv",
      "accountId": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "status": "COMPLETED",
      "transcriptionConfigurationId": "voice_transcriptionconfiguration_0tce7fytzhr04xvxzvxntwashk",
      "sourceId": null,
      "mediaUrl": "https://example.com/audio/it-IT.flac",
      "audioStartedAt": "2026-08-14T18:19:02Z",
      "conversationId": "conv_conversation_01kq0b2vqceb8vy5smkrwvpx5d",
      "conversationUrl": "https://maestro.twilio.com/v1/Conversations/conv_conversation_01kq0b2vqceb8vy5smkrwvpx5d",
      "participants": [
        { "audioChannelIndex": 1, "type": "CUSTOMER", "address": "+18005550100", "name": "Dana A." },
        { "audioChannelIndex": 2, "type": "AI_AGENT", "address": "+18005550101", "name": "AI Assistant" }
      ],
      "duration": 47,
      "resolvedConfiguration": {
        "transcriptionEngine": "google",
        "speechModel": "chirp_2",
        "language": "it-IT",
        "conversationConfigurationId": "conv_configuration_5pe8jw3ahdmsh7zr06yh4d45x1",
        "participantDefaults": [
          { "audioChannelIndex": 1, "type": "CUSTOMER" },
          { "audioChannelIndex": 2, "type": "AI_AGENT" }
        ]
      },
      "createdAt": "2026-08-14T18:19:02Z",
      "updatedAt": "2026-08-14T18:19:10Z",
      "url": "https://voice.twilio.com/v3/Transcriptions/voice_transcription_72c3dv9f7r97j85angc18z4bjv"
    },
    {
      "id": "voice_transcription_05b5208fvx8dft0n5f85v1bdyz",
      "accountId": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "status": "COMPLETED",
      "transcriptionConfigurationId": "voice_transcriptionconfiguration_0tce7fytzhr04xvxzvxntwashk",
      "sourceId": null,
      "mediaUrl": "https://example.com/audio/en-US.flac",
      "audioStartedAt": "2026-08-14T18:19:02Z",
      "conversationId": "conv_conversation_01kq0c7htg4m2n9r5x8vw3pqad",
      "conversationUrl": "https://maestro.twilio.com/v1/Conversations/conv_conversation_01kq0c7htg4m2n9r5x8vw3pqad",
      "participants": [
        { "audioChannelIndex": 1, "type": "CUSTOMER", "address": "+18005550100", "name": "Ravi P." },
        { "audioChannelIndex": 2, "type": "AI_AGENT", "address": "+18005550101", "name": "AI Assistant" }
      ],
      "duration": 63,
      "resolvedConfiguration": {
        "transcriptionEngine": "google",
        "speechModel": "chirp_2",
        "language": "en-US",
        "conversationConfigurationId": "conv_configuration_5pe8jw3ahdmsh7zr06yh4d45x1",
        "participantDefaults": [
          { "audioChannelIndex": 1, "type": "CUSTOMER" },
          { "audioChannelIndex": 2, "type": "AI_AGENT" }
        ]
      },
      "createdAt": "2026-08-14T18:19:02Z",
      "updatedAt": "2026-08-14T18:19:10Z",
      "url": "https://voice.twilio.com/v3/Transcriptions/voice_transcription_05b5208fvx8dft0n5f85v1bdyz"
    }
  ],
  "meta": {
    "key": "transcriptions",
    "pageSize": 2,
    "nextToken": "Y3JlYXRlZEF0PTIwMjYtMDgtMTRUMTg6MTk6MDIuNjkyWiZpZD12b2ljZV90cmFuc2NyaXB0aW9uXzA1YjUyMDhmdng4ZGZ0MG41Zjg1djFiZHl6Jl9fc2Y9MA",
    "previousToken": null
  }
}
```

> \[!NOTE]
>
> Pagination uses opaque cursors, not page numbers. To fetch the next page, send the request again with `pageToken` set to the `meta.nextToken` from the previous response; use `meta.previousToken` to page backward. A token is `null` when there is no page in that direction.

## Error codes

Batch Transcription uses the `175xx` error range. Where an error occurs determines how you see it:

* **Request validation errors** are returned synchronously in the HTTP response when you call [Create a Transcription](#create-a-transcription). No transcription is created.
* **Listing errors** are returned by [List Transcriptions](#list-transcriptions). [17535](/docs/api/errors/17535) reports that a `sourceId` has more stored transcriptions than the service can paginate; it isn't caused by the query parameters, and retrying or narrowing the filters returns the same error.
* **Processing errors** happen after the request is accepted. The transcription is marked `failed` and the error is logged to the [Debugger](/docs/usage/troubleshooting/debugging-your-application).
* **Status callback errors** don't affect the transcription itself. See [Webhook retry behavior](#webhook-retry-behavior) and [Webhook payload size limit](#webhook-payload-size-limit).

### Request validation errors

Twilio returns these as an HTTP error response with an RFC 9457 body. The request is rejected before any processing begins, so no transcription is created and nothing is retried.

| Error code                      | HTTP | Message                                                |
| :------------------------------ | :--- | :----------------------------------------------------- |
| [17500](/docs/api/errors/17500) | 400  | Missing `sourceId` or `mediaUrl`                       |
| [17501](/docs/api/errors/17501) | 400  | Invalid `transcriptionConfigurationId`                 |
| [17502](/docs/api/errors/17502) | 400  | Invalid `sourceId` — not a valid Recording SID         |
| [17503](/docs/api/errors/17503) | 400  | Invalid `mediaUrl` (unsupported scheme or malformed)   |
| [17510](/docs/api/errors/17510) | 400  | Invalid participant count                              |
| [17511](/docs/api/errors/17511) | 400  | Invalid `audioChannelIndex`. Must be 1 or 2            |
| [17512](/docs/api/errors/17512) | 400  | Non-integer `audioChannelIndex`                        |
| [17513](/docs/api/errors/17513) | 400  | Duplicate audio channel                                |
| [17514](/docs/api/errors/17514) | 400  | Invalid participant `type`                             |
| [17515](/docs/api/errors/17515) | 400  | Inconsistent participant types                         |
| [17516](/docs/api/errors/17516) | 400  | Participants must include at least one `CUSTOMER`      |
| [17517](/docs/api/errors/17517) | 400  | Missing participant `address`                          |
| [17530](/docs/api/errors/17530) | 404  | Transcription configuration not found                  |
| [17531](/docs/api/errors/17531) | 403  | Cannot transcribe — account has PCI/HIPAA restrictions |
| [17532](/docs/api/errors/17532) | 403  | Account restricted — V2 transcription customer         |
| [17533](/docs/api/errors/17533) | 400  | Recording not eligible for transcription               |
| [17534](/docs/api/errors/17534) | 422  | Idempotency key payload mismatch                       |

### Processing errors

Twilio accepted the request but couldn't complete the transcription. The transcription's `status` becomes `failed`, and the error appears in the Debugger rather than in an HTTP response.

| Error code                      | Message                                     |
| :------------------------------ | :------------------------------------------ |
| [17550](/docs/api/errors/17550) | Invalid media URL                           |
| [17551](/docs/api/errors/17551) | Failed to download audio file               |
| [17552](/docs/api/errors/17552) | Failed to download media file: not found    |
| [17553](/docs/api/errors/17553) | Failed to download media file: unauthorized |
| [17554](/docs/api/errors/17554) | Media content is empty                      |
| [17555](/docs/api/errors/17555) | Media duration exceeds maximum (8 hours)    |
| [17556](/docs/api/errors/17556) | Media format is not supported               |
| [17557](/docs/api/errors/17557) | Media sample rate below minimum (8 kHz)     |
| [17558](/docs/api/errors/17558) | Corrupted media                             |
| [17559](/docs/api/errors/17559) | Too many channels. Maximum is 2             |
| [17560](/docs/api/errors/17560) | Media size exceeds maximum (3 GiB)          |
| [17561](/docs/api/errors/17561) | Failed to transcribe                        |

> \[!NOTE]
>
> For the full list of Twilio error codes, see the [Error and Warning Dictionary](/docs/api/errors).