Skip to contentSkip to navigationSkip to topbar
Twilio Docs
Page tools
On this page
Looking for more inspiration?Visit the

Transcriptions resource

On this reference page, you'll learn the properties, methods, and parameters for the Transcriptions resource. See Related how-to documentation to learn the steps to use the info on this page.

A Transcription resource represents the transcribed text and metadata from a transcribed recording of a voice call.

The transcription text comes from converting an audio recording to readable text. To generate transcriptions from call recordings, use the TwiML <Record> verb and set transcribe="true".

(information)

PCI compliance

Call recordings aren't Payment Card Industry (PCI) compliant by default. To use Voice Recordings in a PCI workflow, enable PCI Mode in the Twilio Console(link takes you to an external page).

To transcribe voice recordings, use the <Transcription> TwiML noun. Native and Marketplace transcriptions aren't available when PCI Mode is enabled.

(warning)

Warning

If you request recording transcription, your account incurs additional charges. Transcription is a paid feature. Twilio only transcribes recordings initiated with the TwiML <Record> verb and that have a duration no longer than two minutes in length.
To learn about pricing, see the transcriptions pricing page(link takes you to an external page).

Transcriptions properties

transcriptions-properties page anchor
Property nameTypeRequiredPIIDescriptionChild properties
endinteger

Optional

Not PII
firstPageUristring<uri>

Optional

Not PII
nextPageUristring<uri>

Optional

Not PII
pageinteger

Optional

Not PII
pageSizeinteger

Optional

Not PII
previousPageUristring<uri>

Optional

Not PII
startinteger

Optional

Not PII
uristring<uri>

Optional

Not PII
transcriptionsarray[object]

Optional

Not PII

Retrieve a Transcription

retrieve-a-transcription page anchor

GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Transcriptions/{Sid}.json

Returns the JSON metadata for the Transcription.

  • The Transcriptions resource doesn't support CSV and HTML formatted responses.
    Requests made for CSV and HTML files return an HTTP 404 status code.

  • To retrieve only the transcription text, append ".txt" to the Transcriptions resource's URI:

    /2010-04-01/Accounts/{AccountSid}/Transcriptions/{TranscriptionSid}.txt

Path parameters

path-parameters page anchor
Property nameTypeRequiredPIIDescription
accountSidSID<AC>
required
Not PII

The SID of the Account that created the Transcription resource to fetch.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34
sidSID<TR>
required
Not PII

The Twilio-provided string that uniquely identifies the Transcription resource to fetch.

Pattern: ^TR[0-9a-fA-F]{32}$Min length: 34Max length: 34
Retrieve a TranscriptionLink to code sample: Retrieve a Transcription
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function fetchTranscription() {

11
  const transcription = await client

12
    .transcriptions("TRXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

13
    .fetch();

14


15
  console.log(transcription.accountSid);

16
}

17


18
fetchTranscription();

Response

Note about this response
1
{

2
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

3
  "api_version": "2008-08-01",

4
  "date_created": "Sun, 13 Feb 2011 02:12:08 +0000",

5
  "date_updated": "Sun, 13 Feb 2011 02:30:01 +0000",

6
  "duration": "1",

7
  "price": "-0.05000",

8
  "price_unit": "USD",

9
  "recording_sid": "REaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

10
  "sid": "TRXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

11
  "status": "failed",

12
  "transcription_text": "(blank)",

13
  "type": "fast",

14
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Transcriptions/TRaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"

15
}

Retrieve a list of Transcriptions

retrieve-a-list-of-transcriptions page anchor

GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Transcriptions.json

Returns a list of Transcriptions generated from all recordings in an account.

The response contains a paginated list.

Path parameters

path-parameters-1 page anchor
Property nameTypeRequiredPIIDescription
accountSidSID<AC>
required
Not PII

The SID of the Account that created the Transcription resources to read.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

Query parameters

query-parameters page anchor
Property nameTypeRequiredPIIDescription
pageSizeinteger<int64>

Optional

Not PII

How many resources to return in each list page. The default is 50, and the maximum is 1000.

Minimum: 1Maximum: 1000
pageinteger

Optional

Not PII

The page index. This value is simply for client state.

Minimum: 0
pageTokenstring

Optional

Not PII

The page token. This is provided by the API.

Retrieve a list of TranscriptionsLink to code sample: Retrieve a list of Transcriptions
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function listTranscription() {

11
  const transcriptions = await client.transcriptions.list({ limit: 20 });

12


13
  transcriptions.forEach((t) => console.log(t.end));

14
}

15


16
listTranscription();

Response

Note about this response
1
{

2
  "end": 0,

3
  "first_page_uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Transcriptions.json?PageSize=1&Page=0",

4
  "next_page_uri": null,

5
  "page": 0,

6
  "page_size": 1,

7
  "previous_page_uri": null,

8
  "start": 0,

9
  "transcriptions": [

10
    {

11
      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

12
      "api_version": "2008-08-01",

13
      "date_created": "Thu, 25 Aug 2011 20:59:45 +0000",

14
      "date_updated": "Thu, 25 Aug 2011 20:59:45 +0000",

15
      "duration": "10",

16
      "price": "0.00000",

17
      "price_unit": "USD",

18
      "recording_sid": "REaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

19
      "sid": "TRaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

20
      "status": "completed",

21
      "transcription_text": null,

22
      "type": "fast",

23
      "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Transcriptions/TRaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"

24
    }

25
  ],

26
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Transcriptions.json?PageSize=1&Page=0"

27
}

To access a full list of transcriptions from a given Recording, pass the RecordingSid to the Recording resource:

/2010-04-01/Accounts/{YourAccountSid}/Recordings/{RecordingSid}/Transcriptions.json

To fetch Transcriptions from a Recording, write a cURL command that resembles the following:

1
curl -G https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Recordings/REXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Transcriptions.json \

2
     -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'

  • To return an XML-formatted response, change the end of this URI from .json to .xml.

  • The Recording Transcription resource doesn't support CSV and HTML formatted responses.
    Requests made for CSV and HTML files return an HTTP 404 status code.

  • To return only the transcription text, append ".txt" to the Transcription resource's URI:

    1
    curl -G https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Recordings/REXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Transcriptions.txt \

    2
      -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Delete a Transcription

delete-a-transcription page anchor

DELETE https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Transcriptions/{Sid}.json

Delete a transcription from your account.

If the request succeeds, Twilio returns HTTP 204 (No Content) with no body.

Path parameters

path-parameters-2 page anchor
Property nameTypeRequiredPIIDescription
accountSidSID<AC>
required
Not PII

The SID of the Account that created the Transcription resources to delete.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34
sidSID<TR>
required
Not PII

The Twilio-provided string that uniquely identifies the Transcription resource to delete.

Pattern: ^TR[0-9a-fA-F]{32}$Min length: 34Max length: 34
Delete a TranscriptionLink to code sample: Delete a Transcription
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function deleteTranscription() {

11
  await client.transcriptions("TRXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX").remove();

12
}

13


14
deleteTranscription();