Sessions

Overview

A session is the lifetime of one room, from the first participant joining to the last one leaving. These endpoints list the sessions in a project. For one session, they return its participants, its events, and the connection statistics the dashboard shows in its session view.

Listing and reading sessions need the Read role on the project. For a session transcript, logs, traces, metrics, or recording, see Session observability, which needs the Admin role.

Recent sessions appear in stages

A session that just ended takes a few minutes to appear in full. Until its statistics arrive, it returns without detail and with no participants, and its status can still read SESSION_STATUS_ACTIVE. Retry rather than treating it as missing.

Listing sessions returns the last 24 hours unless you set a range. The filter.range.endTime parameter defaults to now, and filter.range.startTime to 24 hours before the end, so set either one or both to read further back. The range can be at most 45 days. A longer range returns 400.

The list leaves out the sessions of agent simulation runs.

To call these endpoints from the CLI, use the lk analytics session commands, for example lk analytics session list --user-auth. The lk analytics session list command lists the last 14 days by default.

The session object

A room session, as ListProjectSessions returns it. Only the detail from GetSession has bandwidth and connection time.

sessionIdstring

The room session ID (RM_...).

roomNamestring

The name of the room the session ran in.

statusSessionStatus

The status of the session. It is ACTIVE until LiveKit records that the session closed, so a session that stopped reporting can be ACTIVE and have an endedAt.

To learn more, see SessionStatus.

startedAttimestamp

When the session started.

endedAttimestamp

The time the session ended. Unset while the session is live. For a session that stopped reporting, this is the time of its last report, also when its status is ACTIVE.

numParticipantsint32

The number of distinct participants, by identity, that connected for more than zero seconds during the session. This is not a live count: a closed session keeps its total.

tagsArray<string>

The tags recorded on the session.

hasDetailDataboolean

True when the full detail of the session is final. While false, LiveKit still finalizes the end time, the participant counts, and the duration. When true, the detail RPCs return complete data.

lastActivetimestamp

When the session last reported activity.

The session object

{
  "sessionId": string,
  "roomName": string,
  "status": SessionStatus,
  "startedAt": timestamp,
  "endedAt": timestamp,
  "numParticipants": int32,
  "tags": Array<string>,
  "hasDetailData": boolean,
  "lastActive": timestamp
}

List project sessions

GET

/v0/projects/{projectId}/sessions

Lists the room sessions of a project, newest first.

Returns a list of Session objects, with a pageInfo cursor.

Path parameters

projectId

Required

string

The project ID (p_...).

Query parameters

page.cursorstring

The cursor of the page to return: the nextCursor of the previous page. When empty, the list starts at the first item.

page.pageSizeint32

The maximum number of items to return. When 0, the list uses its default page size.

filter.range.startTimestring (date-time)

The start of the range, included. Unset means 24 hours before the end.

filter.range.endTimestring (date-time)

The end of the range, excluded. Unset means now.

filter.statusesArray<SessionStatus>

The statuses to match. A session matches when it has one of the statuses. When empty, a session with any status matches.

To learn more, see SessionStatus.

filter.roomNamestring

A prefix of the room name. Returns only the sessions whose room name starts with this value. The match is case-sensitive. For example, demo- matches demo-1 and demo-lobby.

filter.sessionIdstring

The ID of a room session (RM_...). Returns only the session with this exact ID.

filter.tagsArray<string>

The tags to match. A session matches when it has one of the tags.

filter.agentIdstring

The ID of a cloud agent (CA_...). Returns only the sessions that this agent served.

sortOrderSortOrder

The sort direction of startedAt. Sessions sort only on startedAt. Defaults to descending (newest first).

To learn more, see SortOrder.

Request

curl -X GET "https://beta-api.livekit.cloud/v0/projects/${PROJECT_ID}/sessions" \
  -H "Authorization: Bearer $LIVEKIT_SESSION_TOKEN"

Response

{
  "items": [
    {
      "sessionId": "RM_u52jUOHjoTIF",
      "roomName": "support-4821",
      "status": "SESSION_STATUS_CLOSED",
      "startedAt": "2026-01-15T01:38:53Z",
      "endedAt": "2026-01-15T01:43:12Z",
      "numParticipants": 2,
      "tags": [],
      "hasDetailData": true,
      "lastActive": "2026-01-15T01:43:12Z"
    }
  ],
  "pageInfo": {
    "nextCursor": "",
    "hasMore": false
  }
}

Get session

GET

/v0/projects/{projectId}/sessions/{sessionId}

Returns one room session. The response has the session that the list returns, and a detail with the participants and the metric timelines.

Path parameters

projectId

Required

string

The project ID (p_...).

sessionId

Required

string

The session ID (RM_...).

Response fields

sessionSession

The session value.

To learn more, see Session.

detailSessionDetail

The detail of the session. Absent while LiveKit finalizes the detail. See hasDetailData on session.

To learn more, see SessionDetail.

Request

curl -X GET "https://beta-api.livekit.cloud/v0/projects/${PROJECT_ID}/sessions/${SESSION_ID}" \
  -H "Authorization: Bearer $LIVEKIT_SESSION_TOKEN"

Response

{
  "session": {
    "sessionId": "RM_u52jUOHjoTIF",
    "roomName": "support-4821",
    "status": "SESSION_STATUS_CLOSED",
    "startedAt": "2026-01-15T01:38:53Z",
    "endedAt": "2026-01-15T01:43:12Z",
    "numParticipants": 2,
    "tags": [],
    "hasDetailData": true,
    "lastActive": "2026-01-15T01:43:12Z"
  },
  "detail": {
    "sessionId": "RM_u52jUOHjoTIF",
    "roomName": "support-4821",
    "status": "SESSION_STATUS_CLOSED",
    "startedAt": "2026-01-15T01:38:53Z",
    "endedAt": "2026-01-15T01:43:12Z",
    "numParticipants": 2,
    "bandwidthIn": "319879",
    "bandwidthOut": "230152",
    "connectionSeconds": "514",
    "participants": [
      {
        "participantIdentity": "caller-4821",
        "participantName": "Alex Rivera",
        "joinedAt": "2026-01-15T01:38:55Z",
        "leftAt": "2026-01-15T01:43:11Z",
        "publishedSources": {
          "cameraTrack": false,
          "microphoneTrack": true,
          "screenShareTrack": false,
          "screenShareAudio": false
        },
        "location": "United States",
        "region": "US Central A",
        "sessions": [
          {
            "participantSessionId": "PA_LY3m8dJJVq0Q",
            "joinedAt": "2026-01-15T01:38:55Z",
            "leftAt": "2026-01-15T01:43:11Z",
            "durationSeconds": "256",
            "location": "United States",
            "region": "US Central A",
            "connectionType": "UDP",
            "connectionTimeMs": 175,
            "deviceModel": "Mac17,8",
            "os": "mac",
            "browser": "chrome",
            "sdkVersion": "2.15.8"
          }
        ]
      },
      {
        "participantIdentity": "agent-AJ_3kPq8vRtNmXw",
        "participantName": "",
        "joinedAt": "2026-01-15T01:38:54Z",
        "leftAt": "2026-01-15T01:43:12Z",
        "publishedSources": {
          "cameraTrack": false,
          "microphoneTrack": true,
          "screenShareTrack": false,
          "screenShareAudio": false
        },
        "location": "United States",
        "region": "US Central A",
        "sessions": [
          {
            "participantSessionId": "PA_R0MTmk2ZrIxs",
            "joinedAt": "2026-01-15T01:38:54Z",
            "leftAt": "2026-01-15T01:43:12Z",
            "durationSeconds": "258",
            "location": "United States",
            "region": "US Central A",
            "connectionType": "UDP",
            "connectionTimeMs": 243,
            "deviceModel": "",
            "os": "linux",
            "browser": "",
            "sdkVersion": "1.3.2"
          }
        ]
      }
    ],
    "quality": [
      {
        "timestamp": "2026-01-15T01:40:00Z",
        "value": 0.9
      }
    ],
    "publishBps": [
      {
        "timestamp": "2026-01-15T01:40:00Z",
        "value": 34097.2
      }
    ],
    "subscribeBps": [
      {
        "timestamp": "2026-01-15T01:40:00Z",
        "value": 35428.8
      }
    ],
    "publishFps": [
      {
        "timestamp": "2026-01-15T01:40:00Z",
        "value": 0
      }
    ],
    "subscribeFps": [
      {
        "timestamp": "2026-01-15T01:40:00Z",
        "value": 0
      }
    ],
    "tags": [],
    "participantsPage": {
      "nextCursor": "",
      "hasMore": false
    }
  }
}

List session participants

GET

/v0/projects/{projectId}/sessions/{sessionId}/participants

Lists the participants of a room session, one item for each identity. Defaults to newest join first. Each item has the participant sessions of the participant (PA_...), each with the client that it connected from.

Returns a list of ParticipantInfo objects, with a pageInfo cursor.

Path parameters

projectId

Required

string

The project ID (p_...).

sessionId

Required

string

The session ID (RM_...).

Query parameters

page.cursorstring

The cursor of the page to return: the nextCursor of the previous page. When empty, the list starts at the first item.

page.pageSizeint32

The maximum number of items to return. When 0, the list uses its default page size.

sortByParticipantSortField

The field to sort by. Defaults to joinedAt.

To learn more, see ParticipantSortField.

sortOrderSortOrder

The sort direction of sortBy. Defaults to descending (newest first).

To learn more, see SortOrder.

Request

curl -X GET "https://beta-api.livekit.cloud/v0/projects/${PROJECT_ID}/sessions/${SESSION_ID}/participants" \
  -H "Authorization: Bearer $LIVEKIT_SESSION_TOKEN"

Response

{
  "items": [
    {
      "participantIdentity": "caller-4821",
      "participantName": "Alex Rivera",
      "joinedAt": "2026-01-15T01:38:55Z",
      "leftAt": "2026-01-15T01:43:11Z",
      "publishedSources": {
        "cameraTrack": false,
        "microphoneTrack": true,
        "screenShareTrack": false,
        "screenShareAudio": false
      },
      "location": "United States",
      "region": "US Central A",
      "sessions": [
        {
          "participantSessionId": "PA_LY3m8dJJVq0Q",
          "joinedAt": "2026-01-15T01:38:55Z",
          "leftAt": "2026-01-15T01:43:11Z",
          "durationSeconds": "256",
          "location": "United States",
          "region": "US Central A",
          "connectionType": "UDP",
          "connectionTimeMs": 175,
          "deviceModel": "Mac17,8",
          "os": "mac",
          "browser": "chrome",
          "sdkVersion": "2.15.8"
        }
      ]
    },
    {
      "participantIdentity": "agent-AJ_3kPq8vRtNmXw",
      "participantName": "",
      "joinedAt": "2026-01-15T01:38:54Z",
      "leftAt": "2026-01-15T01:43:12Z",
      "publishedSources": {
        "cameraTrack": false,
        "microphoneTrack": true,
        "screenShareTrack": false,
        "screenShareAudio": false
      },
      "location": "United States",
      "region": "US Central A",
      "sessions": [
        {
          "participantSessionId": "PA_R0MTmk2ZrIxs",
          "joinedAt": "2026-01-15T01:38:54Z",
          "leftAt": "2026-01-15T01:43:12Z",
          "durationSeconds": "258",
          "location": "United States",
          "region": "US Central A",
          "connectionType": "UDP",
          "connectionTimeMs": 243,
          "deviceModel": "",
          "os": "linux",
          "browser": "",
          "sdkVersion": "1.3.2"
        }
      ]
    }
  ],
  "pageInfo": {
    "nextCursor": "",
    "hasMore": false
  }
}

List session events

GET

/v0/projects/{projectId}/sessions/{sessionId}/events

Lists the events of a room session. Defaults to oldest first. The page info has no total.

When types is empty, the list has these seven types: PARTICIPANT_JOINED, PARTICIPANT_LEFT, PARTICIPANT_ACTIVE, PARTICIPANT_RESUMED, ROOM_CREATED, ROOM_ENDED, and API_CALL. To get other types, such as TRACK_PUBLISHED, set types. To get the events of one participant session, set participantSessionId. When you set participantSessionId and types is empty, the list has these eleven types: PARTICIPANT_JOINED, PARTICIPANT_LEFT, PARTICIPANT_RESUMED, PARTICIPANT_ACTIVE, TRACK_MUTED, TRACK_UNMUTED, TRACK_PUBLISHED, TRACK_UNPUBLISHED, TRACK_SUBSCRIBED, TRACK_SUBSCRIBE_REQUESTED, and TRACK_SUBSCRIBE_FAILED.

Each type matches exactly, so TRACK_PUBLISHED does not also return TRACK_PUBLISHED_UPDATE. The payload of an event has only a fixed set of fields. It does not include participant attributes, participant metadata, or the request bodies of API calls. Each event and participant item has the identity of the participant. For a SIP caller, the identity can be a phone number.

LiveKit keeps events for 60 days. This can be shorter than the other data of the session, so an older session can have no events. An ACTIVE session lists the events recorded until now.

Errors: an unknown type or a malformed participant session ID returns InvalidArgument. An unknown session returns NotFound.

Returns a list of SessionEvent objects, with a pageInfo cursor.

Path parameters

projectId

Required

string

The project ID (p_...).

sessionId

Required

string

The session ID (RM_...).

Query parameters

page.cursorstring

The cursor of the page to return: the nextCursor of the previous page. When empty, the list starts at the first item.

page.pageSizeint32

The maximum number of items to return. When 0, the list uses its default page size.

typesArray<string>

The event types to return, by name, such as TRACK_PUBLISHED. The names are the values of the LiveKit AnalyticsEventType. Each name matches exactly. When empty, the list has the default types. See ListSessionEvents. An unknown name returns InvalidArgument.

participantSessionIdstring

The ID of a participant session (PA_...), as in participantSessionId of a participant session from ListSessionParticipants. Returns only the events of this participant session. Room events and API calls have no participant session, so the list does not include them. A value that is not a PA_ ID returns InvalidArgument.

sortOrderSortOrder

The sort direction of timestamp. Defaults to ascending (oldest first).

To learn more, see SortOrder.

Request

curl -X GET "https://beta-api.livekit.cloud/v0/projects/${PROJECT_ID}/sessions/${SESSION_ID}/events" \
  -H "Authorization: Bearer $LIVEKIT_SESSION_TOKEN"

Response

{
  "items": [
    {
      "participantIdentity": "caller-4821",
      "type": "PARTICIPANT_JOINED",
      "timestamp": "2026-01-15T01:38:55Z",
      "payload": {
        "disconnectReason": "UNKNOWN_REASON",
        "participantKind": "STANDARD",
        "reconnectReason": "RR_UNKNOWN"
      },
      "participantSessionId": "PA_LY3m8dJJVq0Q"
    }
  ],
  "pageInfo": {
    "nextCursor": "",
    "hasMore": false
  }
}

Types

Types used by these endpoints, alongside the session object.

DataPoint

A point of a session time series, such as quality, bandwidth, or frame rate.

timestamptimestamp

The start of the sample interval.

valuenumber

The value over that interval.

ParticipantInfo

A participant identity of a room session.

participantIdentitystring

The identity the participant connected with.

participantNamestring

The display name of the participant.

joinedAttimestamp

The time of the first join across the connections of the identity.

leftAttimestamp

The time of the last leave across the connections of the identity. Unset while no leave is recorded, so a participant of an active session with no leftAt can still be connected.

publishedSourcesPublishedSources

The track sources that the participant published during the session.

To learn more, see PublishedSources.

locationstring

The name of the country, for example United States. Unknown when the country is not known.

regionstring

The display name of the LiveKit region. Unknown when the region is not recognized.

sessionsArray<ParticipantSession>

The participant sessions of the participant, oldest join first. There is one for each connection, so each reconnect adds one. The maximum is 50. For a participant with more, this has the oldest 50. Empty when the participant sessions cannot be read. The other fields still return.

To learn more, see ParticipantSession.

ParticipantSession

A participant session: the time from one join of a participant to its leave, with the client that it connected from. A participant that reconnects, from the same device or a different one, has more than one.

participantSessionIdstring

The ID of the participant session (PA_...).

joinedAttimestamp

The time the participant session joined.

leftAttimestamp

The time the participant session left. Unset while no leave is recorded.

durationSecondsint64

The number of seconds from joinedAt to leftAt. While no leave is recorded, the count goes to the end of the room session, or to now when the room session has no end.

locationstring

The name of the country, for example United States. Unknown when the country is not known.

regionstring

The display name of the LiveKit region. Unknown when the region is not recognized.

connectionTypestring

The transport that the client connected over: UDP, TCP, or TURN. Empty when not reported.

connectionTimeMsint32

The time that the client took to connect, in milliseconds.

deviceModelstring

The device model of the client, for example iPhone 15.

osstring

The operating system of the client: ios, android, windows, mac, or linux. Empty when not reported.

browserstring

The browser of the client, for example chrome.

sdkVersionstring

The version of the LiveKit client SDK, for example 2.6.1. The name of the SDK is not recorded.

ParticipantSortField

The field that a participant list sorts by.

This type has these values:

PARTICIPANT_SORT_FIELD_UNSPECIFIED
PARTICIPANT_SORT_FIELD_JOINED_AT
PARTICIPANT_SORT_FIELD_LEFT_AT

PublishedSources

The track sources that a participant published.

cameraTrackboolean

True when the participant published a camera track.

microphoneTrackboolean

True when the participant published a microphone track.

screenShareTrackboolean

True when the participant published a screen share track.

screenShareAudioboolean

True when the participant published screen share audio.

SessionDetail

The detail of a room session. It has the fields of Session, and also totals, the first page of participants, and a timeline for each metric.

All timelines use the same time buckets, sized from the length of the session. Each timeline has one point for each bucket, with 0 where a bucket has no data.

sessionIdstring

The room session ID (RM_...).

roomNamestring

The name of the room the session ran in.

statusSessionStatus

The session status, as on Session.

To learn more, see SessionStatus.

startedAttimestamp

When the session started.

endedAttimestamp

When the session ended, as on Session.

numParticipantsint32

The number of participants. This is the same count as numParticipants in Session.

bandwidthInint64

The number of bytes that participants published, for all track types.

bandwidthOutint64

The number of bytes that participants subscribed to, for all track types.

connectionSecondsint64

The total WebRTC connection time in seconds, of standard participants and self-hosted agents. Cloud agents are not included.

participantsArray<ParticipantInfo>

The first page of participants, newest join first. The maximum is 50. When participantsPage.hasMore is true, call ListSessionParticipants to get the next page. Set page.cursor to participantsPage.nextCursor, and leave sortBy and sortOrder unset, or set them to joinedAt and descending.

To learn more, see ParticipantInfo.

qualityArray<DataPoint>

The average connection quality, as a fraction from 0 to 1 of the track score, which goes from 0 to 5.

To learn more, see DataPoint.

publishBpsArray<DataPoint>

The published audio and video bitrate, in bits per second.

To learn more, see DataPoint.

subscribeBpsArray<DataPoint>

The subscribed audio and video bitrate, in bits per second.

To learn more, see DataPoint.

publishFpsArray<DataPoint>

The published video frame rate.

To learn more, see DataPoint.

subscribeFpsArray<DataPoint>

The subscribed video frame rate.

To learn more, see DataPoint.

tagsArray<string>

The tags of the session, the same as in Session.

participantsPagePageInfo

The page info for participants. Unset when the first page cannot be read. The other fields still return, and ListSessionParticipants lists the participants.

To learn more, see PageInfo.

SessionEvent

An event of a room session, such as a participant that joins or a track that is published.

participantIdentitystring

The identity of the participant that the event is about. Empty for a room event, or for an API call that names no participant.

typestring

The type of the event, an AnalyticsEventType name such as PARTICIPANT_JOINED.

timestamptimestamp

When the event was recorded.

payloadobject

The fields of the event. Each field is present only when the event has it. The payload has only these fields:

Participant events: participantKind, disconnectReason, reconnectReason, isMigration, and connectionType.
Track events: trackId, trackType, trackSource, mimeType, and muted.
ROOM_ENDED: reason.
API_CALL: service, method, status, twirpErrorCode, and durationNs.

participantSessionIdstring

The ID of the participant session (PA_...) that the event is about. Empty when participantIdentity is empty.

SessionStatus

The lifecycle state of a session.

This type has these values:

SESSION_STATUS_UNSPECIFIED
SESSION_STATUS_ACTIVE
SESSION_STATUS_CLOSED

SortOrder

The sort direction of a list.

This type has these values:

SORT_ORDER_UNSPECIFIED
SORT_ORDER_ASC
SORT_ORDER_DESC

Overview

The session object

List project sessions

Get session

List session participants

List session events

Types

DataPoint

ParticipantInfo

ParticipantSession

ParticipantSortField

PublishedSources

SessionDetail

SessionEvent

SessionStatus

SortOrder

Ask LiveKit

Keep in touch