Track Events

Track Events can be used to understand the participant's activity during the session, It would get you the reference points in time e.g. when the user has unmuted audio, shared screen, or stopped the video. Every event has a mute property to determine mute status at the time of the event.

Following are the three types of events published for a track,

track.add.success: Published when a track is added

track.update.success: Published when a user has unmuted/muted the track.

track.remove.success: Published when the track has ended

Kind of a track (e.g. audio, video, video screenshare) can be determined by type and source parameter in the track event object.


curl --location --request GET \
    'https://api.100ms.live/v2/analytics/events?type=track.add.success&room_id=<room_id>' \
    --header 'Authorization: Bearer <management_token>'

Allowed Filters

To be specified as query parameters

Name	Type	Description	Required
type	`string`	Type of events to be fetched (valid values `track.add.success`, `track.update.success`, `track.remove.success`) Can be specified multiple times to include more than one event (e.g. `type=track.add.success&` `type=track.update.success`)	yes
room_id	`string`	Unique identifier of the room you wish to fetch events for	yes
session_id	`string`	Unique session identifier (Can be found in using sessions APIs)	no
peer_id	`string`	Unique identifier of peer/participant	no
user_id	`string`	Filter events based on your internal user identifier	no
limit	`int`	Determines the number of event objects to be included in response (Default:`10`, Min: `1`, Max: `100`)	no
start	`string`	Specify next value from the last response to get next set of result.	no

Track Event Object

Attribute	Type	Description
room_id	`string`	Unique identifier of the room (Example: `5f9edc6bd238215aec7700df`)
session_id	`string`	Unique identifier of the session (Example: `5f9edc6bd238215aec7700df`)
room_name	`string`	Room name provided when creating the room
peer_id	`string`	Unique identifier of the peer/participant
user_id	`string`	Your internal user identifier
user_name	`string`	User name of the user
joined_at	`timestamp (in UTC)`	Timestamp when the peer joined the session in RFC3339 format e.g. `2022-02-09T05:53:23.375Z`
role	`string`	Peer role
track_id	`string`	Track id
stream_id	`string`	Reference to internal stream object
type	`string`	Type of track (values: `audio`, `video`)
source	`string`	Source of input (values: `regular`, `screen`)
mute	`bool`	Mute state of track at the time of event
started_at	`timestamp (in UTC)`	Track start time in RFC3339 format e.g. `2022-02-09T05:53:23.375Z`.
stopped_at	`timestamp (in UTC)`	Track stop time in RFC3339 format e.g. `2022-02-09T05:53:23.375Z` (only specified in `track.remove.success` event)

RESPONSE

Status: 200 OK


{
    "limit": 3,
    "total": 6,
    "next": "e88863db-094e-4cf0-b126-ad7840ee24f0:Zv2ehb7:0~Cxn9G9I9AhU-Jl6RiYr-_XEmSYnnk-QLC3Kw4oF1ddvLTE-V4sAEdj8Fi2mx2R93iC1Mu5agwUCY7-LJhH6Ch2yWpp35E3zS7C998Vt3R-s=",
    "events": [
        {
            "version": "2.0",
            "id": "5ff0ce7b-0901-4566-8962-7543613b0456",
            "timestamp": "2023-02-23T10:12:00.78311898Z",
            "type": "track.add.success",
            "data": {
                "room_id": "633a78ee3bea2af508356a34",
                "session_id": "63f73bf05223403c9671c5c9",
                "room_name": "exp",
                "peer_id": "c8e85ab4-d533-4de0-ba7c-4c58a4de6c74",
                "user_id": "187a1a92-150f-4506-83b7-d8a1cd716fb0",
                "user_name": "John",
                "joined_at": "2023-02-23T10:12:00.587243415Z",
                "role": "host",
                "track_id": "d3c7a05d-81ee-48a0-8a6a-ec36be966312",
                "stream_id": "cc6934ca-0c91-4cb7-8a97-293be2d0d8a8",
                "type": "audio",
                "source": "regular",
                "mute": true,
                "started_at": "2023-02-23T10:12:00.781851067Z"
            }
        },
        {
            "version": "2.0",
            "id": "ff3242c5-9838-4979-8f71-23fdd98cc319",
            "timestamp": "2023-02-23T10:20:52.911740569Z",
            "type": "track.update.success",
                "data": {
                "room_id": "633a78ee3bea2af508356a34",
                "session_id": "63f73bf05223403c9671c5c9",
                "room_name": "exp",
                "peer_id": "c8e85ab4-d533-4de0-ba7c-4c58a4de6c74",
                "user_id": "187a1a92-150f-4506-83b7-d8a1cd716fb0",
                "user_name": "John",
                "joined_at": "2023-02-23T10:12:00.587243415Z",
                "role": "host",
                "track_id": "d3c7a05d-81ee-48a0-8a6a-ec36be966312",
                "stream_id": "cc6934ca-0c91-4cb7-8a97-293be2d0d8a8",
                "type": "audio",
                "source": "regular",
                "mute": false,
                "started_at": "2023-02-23T10:12:00.781851067Z"
            }
        },
        {
            "version": "2.0",
            "id": "f64ebeec-9ab2-4d36-b445-affe5cda90a0",
            "timestamp": "2023-02-23T10:22:30.720047276Z",
            "type": "track.remove.success",
            "data": {
                "room_id": "633a78ee3bea2af508356a34",
                "session_id": "63f73bf05223403c9671c5c9",
                "room_name": "exp",
                "peer_id": "c8e85ab4-d533-4de0-ba7c-4c58a4de6c74",
                "user_id": "187a1a92-150f-4506-83b7-d8a1cd716fb0",
                "user_name": "John",
                "joined_at": "2023-02-23T10:12:00.587243415Z",
                "role": "host",
                "track_id": "d3c7a05d-81ee-48a0-8a6a-ec36be966312",
                "stream_id": "cc6934ca-0c91-4cb7-8a97-293be2d0d8a8",
                "type": "audio",
                "source": "regular",
                "mute": false,
                "started_at": "2023-02-23T10:12:00.781851067Z"
                "stopped_at": "2023-02-23T10:22:30.718237635Z"
            }
        }
    ]
}

Why would you use this API?

You can use track events exposed by this API to build tools around user activity which can help you calculate,
- "How long a participant was unmuted?"
- "How long did the teacher turn on their video in the class?"
- "When did a presenter share their screen?"
Active duration of a peer can be calculated as follows,
- Fetch events by specifying peer_id/user_id in the query parameter, this would limit events only to specified peer/user.
- For each track identifiable with track_id you can check type and source properties in the event to find out if track is audio, video, screenshare. (for example if you are looking for audio events, you can check for type: audio, source: regular)
- For all events that share the same 'track_id', we must calculate the total of duration between an event when a participant unmutes and next event when they mute themselves. Refer the pseudocode below.
```
 ## track_events is a list of track add, update, remove events having the same track id
 duration = 0
 last_event = track_events[0]  ## this would be a track.add.success event
 while event in track_events[1...n]
     if event.data.mute == true
         duration += (event.timestamp - last_event.timestamp)  ## last event would have mute = false
     else
         last_event = event
 end
```

Postman collection

You can use our Postman collection to start exploring 100ms APIs.

Refer to the Postman guide to get started with 100ms API collection.

Overview Recording Events

Have a suggestion? Recommend changes ->