Skip to contentSkip to navigationSkip to topbar
Twilio Docs
On this page

Video Log Analyzer API

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.

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

Authentication

authentication page anchor

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.

Get Rooms List

get-rooms-list page anchor

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.

GET https://insights.twilio.com/v1/Video/Rooms
Get Rooms ListLink to code sample: Get Rooms List
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 listVideoRoomSummary() {

11
  const rooms = await client.insights.v1.rooms.list({ limit: 20 });

12


13
  rooms.forEach((r) => console.log(r.accountSid));

14
}

15


16
listVideoRoomSummary();

Output

1
{

2
  "meta": {

3
    "first_page_url": "https://insights.twilio.com/v1/Video/Rooms?PageSize=50&Page=0",

4
    "url": "https://insights.twilio.com/v1/Video/Rooms?PageSize=50&Page=0",

5
    "page_size": 50,

6
    "next_page_url": null,

7
    "key": "rooms",

8
    "page": 0,

9
    "previous_page_url": null

10
  },

11
  "rooms": [

12
    {

13
      "room_type": "go",

14
      "unique_participant_identities": 0,

15
      "codecs": [

16
        "VP8"

17
      ],

18
      "max_participants": 0,

19
      "room_sid": "RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

20
      "create_time": "2015-07-30T20:00:00Z",

21
      "end_reason": "room_ended_via_api",

22
      "duration_sec": 50000000,

23
      "room_status": "in_progress",

24
      "media_region": "us1",

25
      "recording_enabled": false,

26
      "edge_location": "ashburn",

27
      "max_concurrent_participants": 0,

28
      "unique_participants": 0,

29
      "room_name": "room_name",

30
      "created_method": "sdk",

31
      "total_participant_duration_sec": 50000000,

32
      "status_callback_method": "GET",

33
      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

34
      "end_time": "2015-07-30T20:00:00Z",

35
      "total_recording_duration_sec": 50000000,

36
      "processing_state": "complete",

37
      "concurrent_participants": 0,

38
      "status_callback": "http://www.example.com",

39
      "url": "https://insights.twilio.com/v1/Video/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

40
      "links": {

41
        "participants": "https://insights.twilio.com/v1/Video/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants"

42
      }

43
    }

44
  ]

45
}

Query parameters

query-parameters page anchor
Property nameTypeRequiredPIIDescription
RoomTypearray[enum<string>]Optional
Not PII

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

Possible values:
gopeer_to_peergroupgroup_small
Codecarray[enum<string>]Optional
Not PII

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

Possible values:
VP8H264VP9
RoomNamestringOptional
Not PII

Room friendly name.

CreatedAfterstring<date-time>Optional
Not PII

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

CreatedBeforestring<date-time>Optional
Not PII

Only read rooms that started before this ISO 8601 timestamp.

PageSizeintegerOptional
Not PII

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

Minimum: 1Maximum: 1000
PageintegerOptional
Not PII

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

Minimum: 0
PageTokenstringOptional
Not PII

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.

GET https://insights.twilio.com/v1/Video/Rooms/{Room_SID}
Get Video Log Analyzer Data for a RoomLink to code sample: Get Video Log Analyzer Data for a Room
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 fetchVideoRoomSummary() {

11
  const room = await client.insights.v1

12
    .rooms("RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

13
    .fetch();

14


15
  console.log(room.accountSid);

16
}

17


18
fetchVideoRoomSummary();

Output

1
{

2
  "room_type": "go",

3
  "unique_participant_identities": 0,

4
  "codecs": [

5
    "VP8"

6
  ],

7
  "max_participants": 0,

8
  "room_sid": "RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

9
  "create_time": "2015-07-30T20:00:00Z",

10
  "end_reason": "room_ended_via_api",

11
  "duration_sec": 50000000,

12
  "room_status": "in_progress",

13
  "media_region": "us1",

14
  "recording_enabled": false,

15
  "edge_location": "ashburn",

16
  "max_concurrent_participants": 0,

17
  "unique_participants": 0,

18
  "room_name": "room_name",

19
  "created_method": "sdk",

20
  "total_participant_duration_sec": 50000000,

21
  "status_callback_method": "GET",

22
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

23
  "end_time": "2015-07-30T20:00:00Z",

24
  "total_recording_duration_sec": 50000000,

25
  "processing_state": "complete",

26
  "concurrent_participants": 0,

27
  "status_callback": "http://www.example.com",

28
  "url": "https://insights.twilio.com/v1/Video/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

29
  "links": {

30
    "participants": "https://insights.twilio.com/v1/Video/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants"

31
  }

32
}

Path parameters

path-parameters page anchor
Property nameTypeRequiredPIIDescription
RoomSidstringrequired
Not PII

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:

Property nameTypeRequiredDescriptionChild properties
account_sidSID<AC>Optional
Not PII

Account SID associated with this room.

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

Unique identifier for the room.

Pattern: ^RM[0-9a-fA-F]{32}$Min length: 34Max length: 34
room_namestringOptional
Not PII

Room friendly name.

create_timestring<date-time>Optional
Not PII

Creation time of the room.

end_timestring<date-time>Optional
Not PII

End time for the room.

room_typeenum<string>Optional
Not PII

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

Possible values:
gopeer_to_peergroupgroup_small
room_statusenum<string>Optional
Not PII

Status of the room. Can be in_progress or completed.

Possible values:
in_progresscompleted
status_callbackstring<uri>Optional
Not PII

Webhook provided for status callbacks.

status_callback_methodenum<http-method>Optional
Not PII

HTTP method provided for status callback URL.

Possible values:
GETPOST
created_methodenum<string>Optional
Not PII

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

Possible values:
sdkad_hocapi
end_reasonenum<string>Optional
Not PII

Reason the room ended. Can be room_ended_via_api or timeout.

Possible values:
room_ended_via_apitimeout
max_participantsintegerOptional
Not PII

Max number of total participants allowed by the application settings.

unique_participantsintegerOptional
Not PII

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

unique_participant_identitiesintegerOptional
Not PII

Unique number of participant identities.

concurrent_participantsintegerOptional
Not PII

Actual number of concurrent participants.

max_concurrent_participantsintegerOptional
Not PII

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

codecsarray[enum<string>]Optional
Not PII

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

Possible values:
VP8H264VP9
media_regionenum<string>Optional
Not PII

Region of Twilio media servers for the room. See the list of possible media servers here.

Possible values:
us1us2au1br1ie1jp1sg1in1de1gll
duration_secinteger<int64>Optional
Not PII

Total room duration from create time to end time.

total_participant_duration_secinteger<int64>Optional
Not PII

Combined amount of participant time in the room.

total_recording_duration_secinteger<int64>Optional
Not PII

Combined amount of recorded seconds for participants in the room.

processing_stateenum<string>Optional
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_enabledbooleanOptional
Not PII

Boolean indicating if recording is enabled for the room.

edge_locationenum<string>Optional
Not PII

Edge location of Twilio media servers for the room. See the list of public edge locations for the possible values.

Possible values:
ashburndublinfrankfurtsingaporesydneysao_pauloroamingumatillatokyo
urlstring<uri>Optional
Not PII

URL for the room resource.

linksobject<uri-map>Optional
Not PII

Room subresources.

Get Participants List

get-participants-list page anchor

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

GET https://insights.twilio.com/v1/Video/Rooms/{Room_SID}/Participants
Get List of Room ParticipantsLink to code sample: Get List of Room Participants
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 listVideoParticipantSummary() {

11
  const participants = await client.insights.v1

12
    .rooms("RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

13
    .participants.list({ limit: 20 });

14


15
  participants.forEach((p) => console.log(p.participantSid));

16
}

17


18
listVideoParticipantSummary();

Output

1
{

2
  "meta": {

3
    "url": "https://insights.twilio.com/v1/Video/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants?PageSize=50&Page=0",

4
    "key": "participants",

5
    "first_page_url": "https://insights.twilio.com/v1/Video/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants?PageSize=50&Page=0",

6
    "page_size": 50,

7
    "next_page_url": null,

8
    "page": 0,

9
    "previous_page_url": null

10
  },

11
  "participants": [

12
    {

13
      "publisher_info": {},

14
      "edge_location": "ashburn",

15
      "join_time": "2015-07-30T20:00:00Z",

16
      "leave_time": "2015-07-30T20:00:00Z",

17
      "end_reason": "disconnected_via_api",

18
      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

19
      "error_code": 53205,

20
      "media_region": "us1",

21
      "properties": {},

22
      "room_sid": "RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

23
      "error_code_url": "error_code_url",

24
      "participant_sid": "PAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

25
      "codecs": [

26
        "VP8"

27
      ],

28
      "status": "in_progress",

29
      "duration_sec": 50000000,

30
      "participant_identity": "participant_identity",

31
      "url": "https://insights.twilio.com/v1/Video/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/PAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

32
    }

33
  ]

34
}

Path parameters

path-parameters-1 page anchor
Property nameTypeRequiredPIIDescription
RoomSidstringrequired
Not PII

The SID of the Room resource.

Query parameters

query-parameters-1 page anchor
Property nameTypeRequiredPIIDescription
PageSizeintegerOptional
Not PII

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

Minimum: 1Maximum: 1000
PageintegerOptional
Not PII

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

Minimum: 0
PageTokenstringOptional
Not PII

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.

GET https://insights.twilio.com/v1/Video/Rooms/{Room_SID}/Participants/{Partcipant_SID}
Get a Participant's DetailsLink to code sample: Get a Participant's Details
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 fetchVideoParticipantSummary() {

11
  const participant = await client.insights.v1

12
    .rooms("RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

13
    .participants("PAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

14
    .fetch();

15


16
  console.log(participant.participantSid);

17
}

18


19
fetchVideoParticipantSummary();

Output

1
{

2
  "publisher_info": {},

3
  "edge_location": "ashburn",

4
  "join_time": "2015-07-30T20:00:00Z",

5
  "leave_time": "2015-07-30T20:00:00Z",

6
  "end_reason": "disconnected_via_api",

7
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

8
  "error_code": 0,

9
  "media_region": "us1",

10
  "properties": {},

11
  "room_sid": "RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

12
  "error_code_url": "error_code_url",

13
  "participant_sid": "PAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

14
  "codecs": [

15
    "VP8"

16
  ],

17
  "status": "in_progress",

18
  "duration_sec": 50000000,

19
  "participant_identity": "participant_identity",

20
  "url": "https://insights.twilio.com/v1/Video/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants/PAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

21
}

Path parameters

path-parameters-2 page anchor
Property nameTypeRequiredPIIDescription
RoomSidstringrequired
Not PII

The SID of the Room resource.

ParticipantSidstringrequired
Not PII

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:

Property nameTypeRequiredDescriptionChild properties
participant_sidSID<PA>Optional
Not PII

Unique identifier for the participant.

Pattern: ^PA[0-9a-fA-F]{32}$Min length: 34Max length: 34
participant_identitystringOptional
Not PII

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

join_timestring<date-time>Optional
Not PII

When the participant joined the room.

leave_timestring<date-time>Optional
Not PII

When the participant left the room.

duration_secinteger<int64>Optional
Not PII

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

account_sidSID<AC>Optional
Not PII

Account SID associated with the room.

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

Unique identifier for the room.

Pattern: ^RM[0-9a-fA-F]{32}$Min length: 34Max length: 34
statusenum<string>Optional
Not PII

Status of the room. Can be in_progress or completed.

Possible values:
in_progresscompleted
codecsarray[enum<string>]Optional
Not PII

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

Possible values:
VP8H264VP9
end_reasonstringOptional
Not PII

Reason the participant left the room. See the list of possible values here.

error_codeintegerOptional
Not PII

Errors encountered by the participant.

error_code_urlstringOptional
Not PII

Twilio error code dictionary link.

media_regionenum<string>Optional
Not PII

Twilio media region the participant connected to. See the list of possible media servers here.

Possible values:
us1us2au1br1ie1jp1sg1in1de1gll
propertiesobjectOptional
Not PII

Object containing information about the participant's data from the room. See below for more information.

edge_locationenum<string>Optional
Not PII

Name of the edge location the participant connected to. See the list of public edge locations for the possible values.

Possible values:
ashburndublinfrankfurtsingaporesydneysao_pauloroamingumatillatokyo
publisher_infoobjectOptional
Not PII

Object containing information about the SDK name and version. See below for more information.

urlstring<uri>Optional
Not PII

URL of the participant resource.

properties

properties page anchor

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.

publisher_info

publisher_info page anchor

The publisher_info object contains the following keys:

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

end_reason

end_reason page anchor

Below are the possible options for a participant end_reason:

1
disconnected_via_api

2
signaling_connection_error

3
signaling_connection_disconnected

4
signaling_connection_timed_out

5
client_received_an_invalid_signaling_message

6
client_sent_an_invalid_signaling_message

7
room_name_is_invalid

8
room_name_is_too_long

9
room_name_contains_invalid_characters

10
unable_to_create_room

11
unable_to_connect_to_room

12
room_contains_too_many_participants

13
room_not_found

14
max_participants_is_out_of_range

15
room_type_is_not_valid

16
timeout_is_out_of_range

17
status_callback_method_is_invalid

18
status_callback_is_invalid

19
status_is_invalid

20
room_creation_failed

21
room_completed_error

22
the_room_account_limit_was_exceeded

23
invalid_recording_rule

24
approaching_room_or_participant_concurrency_limits

25
recording_operation_requested_is_not_supported_for_the_Room_type

26
participant_identity_is_invalid

27
participant_identity_is_too_long

28
participant_identity_contains_invalid_characters

29
participant_has_too_many_tracks

30
participant_not_found

31
participant_disconnected_because_of_duplicate_identity

32
participant_account_limit_was_exceeded

33
invalid_subscribe_rule

34
track_is_invalid

35
track_name_is_invalid

36
track_name_is_too_long

37
track_name_contains_invalid_characters

38
track_name_is_duplicated

39
client_is_unable_to_create_or_apply_a_local_media_description

40
server_is_unable_to_create_or_apply_a_local_media_description

41
client_is_unable_to_apply_a_remote_media_description

42
server_is_unable_to_apply_a_remote_media_description

43
no_supported_codec

44
media_connection_failed_or_media_activity_ceased

45
unable_to_acquire_configuration

46
unable_to_acquire_TURN_credentials

47
unknown

Need some help?

Terms of service
Privacy Policy

Copyright © 2024 Twilio Inc.