Skip to contentSkip to navigationSkip to topbar
Rate this Page:

Video Log Analyzer API


(warning)

Warning

This page is for reference only. We are no longer onboarding new customers to Programmable Video. Existing customers can continue to use the product until December 5, 2024(link takes you to an external page).
We recommend migrating your application to the API provided by our preferred video partner, Zoom. We've prepared this migration guide(link takes you to an external page) to assist you in minimizing any service disruption.

The Video Log Analyzer REST API provides access to data generated by Programmable Video rooms and participants. Video Logs are available for two days for WebRTC Go rooms, and seven days for all other room types. Summarization and propagation of data may take up to thirty minutes following the end of a room, but most logs are available within ten minutes.


Base URL

base-url page anchor

Video Log Analyzer data is available under the following base URL. The REST API is served over HTTPS; unencrypted HTTP is not supported.


_10
https://insights.twilio.com/v1/Video/Rooms


HTTP requests to the REST API are protected with HTTP Basic authentication(link takes you to an external page). You will use your Twilio account SID as the username and your auth token as the password for HTTP Basic authentication. You can find your account SID and auth token on the console home page. To learn more about how Twilio handles authentication, please refer to our security documentation.


The Rooms list provides a queryable list of Programmable Video Rooms. By default only Rooms completed in the last 24 hours are listed. Use the CreatedBefore and CreatedAfter parameters to query a larger date range.


_10
GET https://insights.twilio.com/v1/Video/Rooms

Get Rooms List

get-rooms-list-1 page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.insights.v1.rooms.list({limit: 20})
_10
.then(rooms => rooms.forEach(r => console.log(r.roomName)));

Output

_45
{
_45
"meta": {
_45
"first_page_url": "https://insights.twilio.com/v1/Video/Rooms?PageSize=50&Page=0",
_45
"url": "https://insights.twilio.com/v1/Video/Rooms?PageSize=50&Page=0",
_45
"page_size": 50,
_45
"next_page_url": "https://insights.twilio.com/v1/Video/Rooms?PageSize=50&Page=1",
_45
"key": "rooms",
_45
"page": 0,
_45
"previous_page_url": "https://insights.twilio.com/v1/Video/Rooms?PageSize=50&Page=0"
_45
},
_45
"rooms": [
_45
{
_45
"room_type": "go",
_45
"unique_participant_identities": 0,
_45
"codecs": [
_45
"VP8"
_45
],
_45
"max_participants": 0,
_45
"room_sid": "RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_45
"create_time": "2015-07-30T20:00:00Z",
_45
"end_reason": "room_ended_via_api",
_45
"duration_sec": 50000000,
_45
"room_status": "in_progress",
_45
"media_region": "us1",
_45
"recording_enabled": false,
_45
"edge_location": "ashburn",
_45
"max_concurrent_participants": 0,
_45
"unique_participants": 0,
_45
"room_name": "room_name",
_45
"created_method": "sdk",
_45
"total_participant_duration_sec": 50000000,
_45
"status_callback_method": "GET",
_45
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_45
"end_time": "2015-07-30T20:00:00Z",
_45
"total_recording_duration_sec": 50000000,
_45
"processing_state": "complete",
_45
"concurrent_participants": 0,
_45
"status_callback": "http://www.example.com",
_45
"url": "https://insights.twilio.com/v1/Video/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_45
"links": {
_45
"participants": "https://insights.twilio.com/v1/Video/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants"
_45
}
_45
}
_45
]
_45
}

URI parameters
RoomTypetype: string[]Not PII
Query Parameter

Type of room. Can be go, peer_to_peer, group, or group_small.

Possible values:
gopeer_to_peergroupgroup_small

Codectype: string[]Not PII
Query Parameter

Codecs used by participants in the room. Can be VP8, H264, or VP9.

Possible values:
VP8H264VP9

RoomNametype: stringNot PII
Query Parameter

Room friendly name.


CreatedAftertype: string<DATE TIME>Not PII
Query Parameter

Only read rooms that started on or after this ISO 8601 timestamp.


CreatedBeforetype: string<DATE TIME>Not PII
Query Parameter

Only read rooms that started before this ISO 8601 timestamp.


PageSizetype: integerNot PII
Query Parameter

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


Pagetype: integerNot PII
Query Parameter

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


PageTokentype: stringNot PII
Query Parameter

The page token. This is provided by the API.


Get Video Log Analyzer Data for a Room

get-video-log-analyzer-data-for-a-room page anchor

The Room resource returns the Video Log Analyzer data for the provided room SID.


_10
GET https://insights.twilio.com/v1/Video/Rooms/{Room_SID}

Get Video Log Analyzer Data for a Room

get-video-log-analyzer-data-for-a-room-1 page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.insights.v1.rooms('RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.fetch()
_10
.then(room => console.log(room.roomName));

Output

_32
{
_32
"room_type": "go",
_32
"unique_participant_identities": 0,
_32
"codecs": [
_32
"VP8"
_32
],
_32
"max_participants": 0,
_32
"room_sid": "RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"create_time": "2015-07-30T20:00:00Z",
_32
"end_reason": "room_ended_via_api",
_32
"duration_sec": 50000000,
_32
"room_status": "in_progress",
_32
"media_region": "us1",
_32
"recording_enabled": false,
_32
"edge_location": "ashburn",
_32
"max_concurrent_participants": 0,
_32
"unique_participants": 0,
_32
"room_name": "room_name",
_32
"created_method": "sdk",
_32
"total_participant_duration_sec": 50000000,
_32
"status_callback_method": "GET",
_32
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"end_time": "2015-07-30T20:00:00Z",
_32
"total_recording_duration_sec": 50000000,
_32
"processing_state": "complete",
_32
"concurrent_participants": 0,
_32
"status_callback": "http://www.example.com",
_32
"url": "https://insights.twilio.com/v1/Video/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"links": {
_32
"participants": "https://insights.twilio.com/v1/Video/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants"
_32
}
_32
}

URI parameters
RoomSidtype: stringNot PII
Path Parameter

The SID of the Room resource.

Room Summary Resource Properties

room-summary-resource-properties page anchor

A Room Summary log is represented by the following properties:

Resource properties
account_sidtype: SID<AC>Not PII

Account SID associated with this room.


room_sidtype: SID<RM>Not PII

Unique identifier for the room.


room_nametype: stringNot PII

Room friendly name.


create_timetype: string<DATE TIME>Not PII

Creation time of the room.


end_timetype: string<DATE TIME>Not PII

End time for the room.


room_typetype: enum<STRING>Not PII

Type of room. Can be go, peer_to_peer, group, or group_small.

Possible values:
gopeer_to_peergroupgroup_small

room_statustype: enum<STRING>Not PII

Status of the room. Can be in_progress or completed.

Possible values:
in_progresscompleted

status_callbacktype: string<URI>Not PII

Webhook provided for status callbacks.


status_callback_methodtype: enum<HTTP METHOD>Not PII

HTTP method provided for status callback URL.

Possible values:
HEADGETPOSTPATCHPUTDELETE

created_methodtype: enum<STRING>Not PII

How the room was created. Can be sdk, ad_hoc, or api.

Possible values:
sdkad_hocapi

end_reasontype: enum<STRING>Not PII

Reason the room ended. Can be room_ended_via_api or timeout.

Possible values:
room_ended_via_apitimeout

max_participantstype: integerNot PII

Max number of total participants allowed by the application settings.


unique_participantstype: integerNot PII

Number of participants. May include duplicate identities for participants who left and rejoined.


unique_participant_identitiestype: integerNot PII

Unique number of participant identities.


concurrent_participantstype: integerNot PII

Actual number of concurrent participants.


max_concurrent_participantstype: integerNot PII

Maximum number of participants allowed in the room at the same time allowed by the application settings.


codecstype: string[]Not PII

Codecs used by participants in the room. Can be VP8, H264, or VP9.

Possible values:
VP8H264VP9

media_regiontype: enum<STRING>Not PII

Region of Twilio media servers for the room. See the list of possible media servers here(link takes you to an external page).

Possible values:
us1us2au1br1ie1jp1sg1in1de1gll

duration_sectype: integer<INT64>Not PII

Total room duration from create time to end time.


total_participant_duration_sectype: integer<INT64>Not PII

Combined amount of participant time in the room.


total_recording_duration_sectype: integer<INT64>Not PII

Combined amount of recorded seconds for participants in the room.


processing_statetype: enum<STRING>Not PII

Video Log Analyzer resource state. Will be either in-progress or complete. in-progress indicates that more details may be appended to the resource. complete indicates no further information will be added.

Possible values:
completein_progress

recording_enabledtype: booleanNot PII

Boolean indicating if recording is enabled for the room.


edge_locationtype: enum<STRING>Not PII

Edge location of Twilio media servers for the room. See the list of public edge locations(link takes you to an external page) for the possible values.

Possible values:
ashburndublinfrankfurtsingaporesydneysao_pauloroamingumatillatokyo

urltype: string<URI>Not PII

URL for the room resource.


linkstype: object<URI MAP>Not PII

Room subresources.


The Participants list returns the participant details for a provided room SID.


_10
GET https://insights.twilio.com/v1/Video/Rooms/{Room_SID}/Participants

Get List of Room Participants

get-list-of-room-participants page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.insights.v1.rooms('RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.participants
_11
.list({limit: 20})
_11
.then(participants => participants.forEach(p => console.log(p.participantSid)));

Output

_34
{
_34
"meta": {
_34
"url": "https://insights.twilio.com/v1/Video/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants?PageSize=50&Page=0",
_34
"key": "participants",
_34
"first_page_url": "https://insights.twilio.com/v1/Video/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants?PageSize=50&Page=0",
_34
"page_size": 50,
_34
"next_page_url": "https://insights.twilio.com/v1/Video/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants?PageSize=50&Page=1",
_34
"page": 0,
_34
"previous_page_url": "https://insights.twilio.com/v1/Video/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants?PageSize=50&Page=0"
_34
},
_34
"participants": [
_34
{
_34
"publisher_info": {},
_34
"edge_location": "ashburn",
_34
"join_time": "2015-07-30T20:00:00Z",
_34
"leave_time": "2015-07-30T20:00:00Z",
_34
"end_reason": "disconnected_via_api",
_34
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_34
"error_code": 53205,
_34
"media_region": "us1",
_34
"properties": {},
_34
"room_sid": "RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_34
"error_code_url": "error_code_url",
_34
"participant_sid": "PAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_34
"codecs": [
_34
"VP8"
_34
],
_34
"status": "in_progress",
_34
"duration_sec": 50000000,
_34
"participant_identity": "participant_identity",
_34
"url": "https://insights.twilio.com/v1/Video/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/PAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_34
}
_34
]
_34
}

URI parameters
RoomSidtype: stringNot PII
Path Parameter

The SID of the Room resource.


PageSizetype: integerNot PII
Query Parameter

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


Pagetype: integerNot PII
Query Parameter

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


PageTokentype: stringNot PII
Query Parameter

The page token. This is provided by the API.


Get Video Log Analyzer data for a Room Participant

get-video-log-analyzer-data-for-a-room-participant page anchor

The Participant resource returns the Video Log Analyzer details for a provided room participant SID.


_10
GET https://insights.twilio.com/v1/Video/Rooms/{Room_SID}/Participants/{Partcipant_SID}

Get a Participant's Details

get-a-participants-details page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.insights.v1.rooms('RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.participants('PAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.fetch()
_11
.then(participant => console.log(participant.participantSid));

Output

_21
{
_21
"publisher_info": {},
_21
"edge_location": "ashburn",
_21
"join_time": "2015-07-30T20:00:00Z",
_21
"leave_time": "2015-07-30T20:00:00Z",
_21
"end_reason": "disconnected_via_api",
_21
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_21
"error_code": 0,
_21
"media_region": "us1",
_21
"properties": {},
_21
"room_sid": "RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_21
"error_code_url": "error_code_url",
_21
"participant_sid": "PAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_21
"codecs": [
_21
"VP8"
_21
],
_21
"status": "in_progress",
_21
"duration_sec": 50000000,
_21
"participant_identity": "participant_identity",
_21
"url": "https://insights.twilio.com/v1/Video/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/PAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_21
}

URI parameters
RoomSidtype: stringNot PII
Path Parameter

The SID of the Room resource.


ParticipantSidtype: stringNot PII
Path Parameter

The SID of the Participant resource.

Participant Summary Resource Properties

participant-summary-resource-properties page anchor

A participant summary is represented by the following properties:

Resource properties
participant_sidtype: SID<PA>Not PII

Unique identifier for the participant.


participant_identitytype: stringNot PII

The application-defined string that uniquely identifies the participant within a Room.


join_timetype: string<DATE TIME>Not PII

When the participant joined the room.


leave_timetype: string<DATE TIME>Not PII

When the participant left the room.


duration_sectype: integer<INT64>Not PII

Amount of time in seconds the participant was in the room.


account_sidtype: SID<AC>Not PII

Account SID associated with the room.


room_sidtype: SID<RM>Not PII

Unique identifier for the room.


statustype: enum<STRING>Not PII

Status of the room. Can be in_progress or completed.

Possible values:
in_progresscompleted

codecstype: string[]Not PII

Codecs detected from the participant. Can be VP8, H264, or VP9.

Possible values:
VP8H264VP9

end_reasontype: stringNot PII

error_codetype: integerNot PII

Errors encountered by the participant.


error_code_urltype: stringNot PII

Twilio error code dictionary link.


media_regiontype: enum<STRING>Not PII

Twilio media region the participant connected to. See the list of possible media servers here(link takes you to an external page).

Possible values:
us1us2au1br1ie1jp1sg1in1de1gll

propertiestype: objectNot PII

Object containing information about the participant's data from the room. See below(link takes you to an external page) for more information.


edge_locationtype: enum<STRING>Not PII

Name of the edge location the participant connected to. See the list of public edge locations(link takes you to an external page) for the possible values.

Possible values:
ashburndublinfrankfurtsingaporesydneysao_pauloroamingumatillatokyo

publisher_infotype: objectNot PII

Object containing information about the SDK name and version. See below(link takes you to an external page) for more information.


urltype: string<URI>Not PII

URL of the participant resource.

The properties object contains the following keys:

NameDescription
recordOnConnectBoolean. Indicates if the participant was recorded as soon as they joined the room.
numAudioTracksNumber of audio tracks from the participant.
numVideoTracksNumber of video tracks from the participant.
numDataTracksNumber of data tracks from the participant.
isAdhocBoolean. Indicates if the participant joined the room ad-hoc.

The publisher_info object contains the following keys:

NameDescription
nameSDK type; e.g., twilio-video-js
sdk_versionSDK version

Below are the possible options for a participant end_reason:


_47
disconnected_via_api
_47
signaling_connection_error
_47
signaling_connection_disconnected
_47
signaling_connection_timed_out
_47
client_received_an_invalid_signaling_message
_47
client_sent_an_invalid_signaling_message
_47
room_name_is_invalid
_47
room_name_is_too_long
_47
room_name_contains_invalid_characters
_47
unable_to_create_room
_47
unable_to_connect_to_room
_47
room_contains_too_many_participants
_47
room_not_found
_47
max_participants_is_out_of_range
_47
room_type_is_not_valid
_47
timeout_is_out_of_range
_47
status_callback_method_is_invalid
_47
status_callback_is_invalid
_47
status_is_invalid
_47
room_creation_failed
_47
room_completed_error
_47
the_room_account_limit_was_exceeded
_47
invalid_recording_rule
_47
approaching_room_or_participant_concurrency_limits
_47
recording_operation_requested_is_not_supported_for_the_Room_type
_47
participant_identity_is_invalid
_47
participant_identity_is_too_long
_47
participant_identity_contains_invalid_characters
_47
participant_has_too_many_tracks
_47
participant_not_found
_47
participant_disconnected_because_of_duplicate_identity
_47
participant_account_limit_was_exceeded
_47
invalid_subscribe_rule
_47
track_is_invalid
_47
track_name_is_invalid
_47
track_name_is_too_long
_47
track_name_contains_invalid_characters
_47
track_name_is_duplicated
_47
client_is_unable_to_create_or_apply_a_local_media_description
_47
server_is_unable_to_create_or_apply_a_local_media_description
_47
client_is_unable_to_apply_a_remote_media_description
_47
server_is_unable_to_apply_a_remote_media_description
_47
no_supported_codec
_47
media_connection_failed_or_media_activity_ceased
_47
unable_to_acquire_configuration
_47
unable_to_acquire_TURN_credentials
_47
unknown


Rate this Page: