Rate this page:

Rest API: Recordings


Twilio Video’s Group Rooms and Recording APIs enable you to record the audio and video shared in a Programmable Video Room. To turn on Recording in a Group Room, set the RecordParticipantsOnConnect property to true when creating the Room. Check the Rooms REST API documentation for additional information.

All Recording resources are located beneath the following Base URL.

Legal implications of call recording

If you choose to record voice or video calls, you need to comply with certain laws and regulations, including those regarding obtaining consent to record (such as California’s Invasion of Privacy Act and similar laws in other jurisdictions). Additional information on the legal implications of call recording can be found here.

Notice: Twilio recommends that you consult with your legal counsel to make sure that you are complying with all applicable laws in connection with communications you record or store using Twilio.

Resource Properties in REST API format
sid<AC> Not PII

The SID of the Account that created the Recording resource.

enum:status Not PII

The status of the recording. Can be: processing, completed, or deleted. processing indicates the recording is still being captured; completed indicates the recording has been captured and is now available for download. deleted means the recording media has been deleted from the system, but its metadata is still available.

date_time<iso8601> Not PII

The date and time in GMT when the resource was created specified in ISO 8601 format.

sid<RT> Not PII

The unique string that we created to identify the Recording resource.

sid Not PII

The SID of the recording source. For a Room Recording, this value is a track_sid.

long Not PII

The size of the recorded track, in bytes.

url Not PII

The absolute URL of the resource.

enum:type Not PII

The recording's media type. Can be: audio or video.

integer? Not PII

The duration of the recording in seconds rounded to the nearest second. Sub-second tracks have a Duration property of 1 second

enum:format Not PII

The file format for the recording. Can be: mka or mkv. Video Room recordings are captured in Matroska container format, mka is for audio files and mkv for video files.

enum:codec Not PII

The codec used to encode the track. Can be: VP8, H264, OPUS, and PCMU.

object Not PII

A list of SIDs related to the recording. Includes the room_sid and participant_sid.


The name that was given to the source track of the recording. If no name is given, the source_sid is used.

long Not PII

The time in milliseconds elapsed between an arbitrary point in time, common to all group rooms, and the moment when the source room of this track started. This information provides a synchronization mechanism for recordings belonging to the same room.

uri_map Not PII

The URLs of related resources.

Note: The duration of media tracks is rounded to the nearest second. Thus, sub-second duration tracks have a Duration property of 1 second.


Returns a single Recording Instance resource identified by a RecordingSid.

Example: Retrieve a Recording


        HTTP GET to the /Media subresource

        Retrieves the media file associated to a given Recording Instance resource identified by a RecordingSid

        When you make a request to this URL, Twilio will generate a temporary URL for accessing this binary data, and issue an HTTP 302 redirect response to your request. The Recording will be returned in the format as described in the metadata, with the Content-Type header set according to the codec used to record the media

        Codec Content-Type value
        VP8 video/webm
        OPUS audio/webm
        PCMU audio/x-matroska
        H264 video/x-matroska

        The URL returned will be available by default for 600 seconds, but this can be configured to a value between 1 and 3600 seconds via the Ttl request param. If the recording is not yet available, a 404 is returned. If the recording is not available (for example, if its status is processing or deleted, or if the track was muted for the duration of the recording), an HTTP 404 response is returned.

        The HTTP GET request accepts the following parameters

        Name Description
        ContentDisposition Optional. Sets the Content-Disposition header of the redirect_to URL. Possible values are attachment or inline. Default value{a|v} (not PII)
        Ttl Optional. Duration in seconds for which the redirect_to URL can be used to retrieve the media file. The default Ttl is 600 seconds. The minimum supported Ttl value is 1 second and the maximum supported value is 3600 seconds. (not PII)

        The Content-Disposition header can be set in this request. By default, the value of this header is{a|v}.

        NOTE: You can play these recordings in media players that support the Matroska file format, like the VLC player. You can also use other programs like Chrome, ffplay or ffplayer to play these recordings. However, these files are optimized for compactness and they are not player-friendly. Hence, you may experience different types of problems when playing these files. For generating player-friendly media files, compose your Recordings using Twilio's Recordings Composition API.

        Example: Retrieve a Recording's Media


              HTTP POST

              Not supported.

              HTTP DELETE

              Deletes the recording media file.

              The metadata for the Recording is preserved for a period of 30 days, and its Status is set to deleted. After this period, the metadata will not be available. By default, Recordings with deleted status are not returned when retrieving the Recordings list. To retrieve deleted Recordings, use the Status=deleted filter.

              Note that the 30 day period starts after the Status is set to deleted. After this period expires, the metadata will not be available.

              Example: Delete a Recording


                    To to delete a large set of Video Recordings, you can use the bulk deletion capabilities available in the Twilio Console.

                    Recordings List Resource

                    Recordings list is available at the following URI:


                    HTTP GET

                    Returns a list of all Track Recordings with paging data.

                    HTTP GET: List filters

                    The following GET query string parameters allow you to limit the list returned. Note, parameters are case-sensitive.

                    Parameters in REST API format
                    get enum:status Not PII

                    Read only the recordings that have this status. Can be: processing, completed, or deleted.

                    get sid Not PII

                    Read only the recordings that have this source_sid.

                    get sid[] Not PII

                    Read only recordings with this grouping_sid, which may include a participant_sid and/or a room_sid.

                    get date_time<iso8601> Not PII

                    Read only recordings that started on or after this ISO 8601 date-time with time zone.

                    get date_time<iso8601> Not PII

                    Read only recordings that started before this ISO 8601 date-time with time zone, given as YYYY-MM-DDThh:mm:ss+|-hh:mm or YYYY-MM-DDThh:mm:ssZ.

                    get ienum:type Not PII

                    Read only recordings that have this media type. Can be either audio or video.

                    Note: deleted Recordings are not returned by default. For retrieving the deleted Recordings list you must explicitly specify Status=deleted.

                    Example: Get all Recordings for a given Room


                                      HTTP POST

                                      Not supported.

                                      HTTP DELETE

                                      Not supported.

                                      Using the Rooms API to find Recordings

                                      To make it easier for customers to find the Recordings from a certain Room, we provide the following affordances for list filtering via the Rooms API:

                                      Example: Get all recordings from a given Room using the Rooms API


                                                        Known issues and limitations

                                                        • Recording files are generated with a format optimized for reliability and compactness. This format is not player friendly. Hence, many media players may not render Recordings media files appropriately. For generating player-friendly media files, compose your Recordings using Twilio's Recordings Composition API.
                                                        Rate this page:

                                                        Need some help?

                                                        We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Community Forums or browsing the Twilio tag on Stack Overflow.


                                                              Thank you for your feedback!

                                                              We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

                                                              Sending your feedback...
                                                              🎉 Thank you for your feedback!
                                                              Something went wrong. Please try again.

                                                              Thanks for your feedback!

                                                              Refer us and get $10 in 3 simple steps!

                                                              Step 1

                                                              Get link

                                                              Get a free personal referral link here

                                                              Step 2

                                                              Give $10

                                                              Your user signs up and upgrade using link

                                                              Step 3

                                                              Get $10

                                                              1,250 free SMSes
                                                              OR 1,000 free voice mins
                                                              OR 12,000 chats
                                                              OR more