Analytics API | LiveKit Docs

Generate an access token for Analytics requests

Analytics API requests are authorized with a LiveKit token. This is generated by a server side SDK,much like generating a token for joining Rooms, except that the token needs the roomList grant.

note

Analytics API is only available to LiveKit Cloud customers with a Scale plan or higher.

lk token create \
  --api-key $LIVEKIT_API_KEY \
  --api-secret $LIVEKIT_SECRET_KEY \
  --list \
  --valid-for 24h

tip

To streamline your workflow with the CLI, add your projects using the command lk project add. This approach spares you from repeatedly entering your --url, --api-key, and --api-secret for each command you execute.

List sessions

To make a request, you'll need to know your project id, which you can see in the URL for your project dashboard. It's the part after /projects/ that starts with p_.

async function listLiveKitSessions() {
  const endpoint = `https://cloud-api.livekit.io/api/project/${PROJECT_ID}/sessions/`;
  try {
    const response = await fetch(endpoint, {
      method: 'GET',
      headers: {
        Authorization: `Bearer ${token}`,
        'Content-Type': 'application/json',
      },
    });

    if (!response.ok) throw new Error('Network response was not ok');

    const data = await response.json();
    console.log(data); // or do whatever you like here
  } catch (error) {
    console.log('There was a problem:', error.message);
  }
}

listLiveKitSessions();

This will return a JSON object like this:

{
  sessions: [
    {
      sessionId,     // string
      roomName,      // string
      createdAt,     // Timestamp
      lastActive,    // Timestamp
      bandwidthIn,   // bytes of bandwidth uploaded
      bandwidthOut,  // bytes of bandwidth downloaded
      egress,         // 0 = never started, 1 = active, 2 = ended
      numParticipants,        // int
      numActiveParticipants, // int
    },
    // ...
  ]
}

Query parameters

limitint

You can limit the number of returned sessions by adding the limit query parameter like ?limit=100.

caution

Higher limit values may result in a timeout from the Analytics API.

pageint

You can page through the results by adding ?page=n&limit=100 to the endpoint URL to get the nth page of results with 100 sessions per page. Pagination starts from 0.

startstring

Specify the start date for the request time range in the format YYYY-MM-DD. Sessions starting on the specified start date will be included in the response.

note

The start date must be within 7 days of the current date.

endstring

Specify the end date for the request time range using the format YYYY-MM-DD. Sessions up to and including this end date will be included in the response.

Examples

# Get the first page and limit the number of sessions to 100.
curl -H "Authorization: Bearer $TOKEN" \
  "https://cloud-api.livekit.io/api/project/$PROJECT_ID/sessions\
  ?page=0&limit=100"


# Fetch sessions from a specified time range.
curl -H "Authorization: Bearer $TOKEN" \
  "https://cloud-api.livekit.io/api/project/$PROJECT_ID/sessions\
  ?start=2024-01-12&end=2024-01-13"

List session details

To get more details about a specific session, you can use the session_id returned from the list sessions request.

async function getLiveKitSessionDetails() {
  const endpoint = `https://cloud-api.livekit.io/api/project/${PROJECT_ID}/sessions/${SESSION_ID}`;
  try {
    const response = await fetch(endpoint, {
      method: 'GET',
      headers: {
        Authorization: `Bearer ${token}`,
        'Content-Type': 'application/json',
      },
    });

    if (!response.ok) throw new Error('Network response was not ok');

    const data = await response.json();
    console.log(data); // or do whatever you like here
  } catch (error) {
    console.log('There was a problem:', error.message);
  }
}

getLiveKitSessionDetails();

This will return a JSON object like this:

{
  roomId,    // string
  roomName,  // string
  bandwidth,  // billable bytes of bandwidth used
  startTime, // Timestamp
  endTime,   // Timestamp
  numParticipants, // int
  participants: [
    {
      participantIdentity, // string
      participantName,     // string
      roomId,              // string
      joinedAt,            // Timestamp
      leftAt,              // Timestamp
      publishedSources: {
        cameraTrack,       // boolean
        microphoneTrack,   // boolean
        screenShareTrack, // boolean
        screenShareAudio, // boolean
      },
      sessions: [
        {
          sessionId, // string
          joinedAt,  // Timestamp
          leftAt,    // Timestamp
        },
        // ...
      ],
    },
    // ...
  ],
}

Timestamp objects are Protobuf Timestamps.