Analytics API

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.

Copied!
# using livekit-cli (https://docs.livekit.io/realtime/cli-setup/)
livekit-cli create-token \
    --api-key $LIVEKIT_API_KEY --api-secret $LIVEKIT_SECRET_KEY \
    --list \
    --valid-for 24h

Copied!
const at = new AccessToken(apiKey, apiSecret, { ttl: 60 * 60 * 24 });
at.addGrant({ roomList: true });

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_.

Copied!
curl -H "Authorization: Bearer $TOKEN" https://cloud-api.livekit.io/api/project/$PROJECT_ID/sessions

Copied!
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:

Copied!
{
  sessions: [
    {
      session_id,     // string
      room_name,      // string
      created_at,     // Timestamp
      last_active,    // Timestamp
      bandwidth_in,   // bytes of bandwidth uploaded
      bandwidth_out,  // bytes of bandwidth downloaded
      egress,         // 0 = never started, 1 = active, 2 = ended
      connection_counts: {
        attempts, // int
        success,  // int
      },
      num_participants,        // int
      num_active_participants, // int
    },
    // ...
  ]
}

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

Copied!
curl -H "Authorization: Bearer $TOKEN" cloud-api.livekit.io/api/project/$PROJECT_ID/sessions/$SESSION_ID

Copied!
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:

Copied!
{
  room_id,    // string
  room_name,  // string
  status,     // 0=closed, 1=active
  bandwidth,  // billable bytes of bandwidth used
  start_time, // Timestamp
  end_time,   // Timestamp
  participants: [
    {
      participant_identity, // string
      participant_name,     // string
      room_id,              // string
      is_active,            // boolean
      joined_at,            // Timestamp
      left_at,              // Timestamp
      published_sources: {
        camera_track,       // boolean
        microphone_track,   // boolean
        screen_share_track, // boolean
        screen_share_audio, // boolean
      },
      sessions: [
        {
          session_id, // string
          joined_at,  // Timestamp
          left_at,    // Timestamp
        },
        // ...
      ],
    },
    // ...
  ],
  num_participants, // int
}

Timestamp objects are Protobuf Timestamps.