Room Summary

GET /v1/room/:roomId/summary

Get a comprehensive summary of a room including total credits consumed, participant count, average stay time, timestamps, and room status. This is ideal for analytics dashboards and post-session reports.

When to Use This

• Analytics dashboards — Display room metrics like total credits and participant engagement
• Post-session reports — Generate summaries after a class ends
• Cost tracking — Monitor credit consumption per room
• Engagement metrics — Track average participant stay time

Request

Headers

Header	Required	Description
VF-ORG-ID	Yes	Your organization ID

URL Parameters

Parameter	Description
roomId	The room identifier used when creating the class

Example Request

curl -X GET https://api.verriflo.com/v1/room/math-101/summary \
  -H "VF-ORG-ID: your-organization-id"

Response

Success (200)

{
  "success": true,
  "data": {
    "roomId": "math-101",
    "roomName": "Calculus I - Morning Session",
    "totalCredits": 1629,
    "totalParticipants": 86,
    "avgStay": 1136,
    "timestamps": {
      "startedAt": "2024-01-15T09:02:30.000Z",
      "endedAt": "2024-01-15T10:30:00.000Z"
    },
    "status": "finished"
  }
}

Response Fields

Field	Type	Description
roomId	string	The room identifier
roomName	string	Display title of the classroom
totalCredits	number	Total credits consumed (1 credit = 1 minute)
totalParticipants	number	Total unique participants who joined
avgStay	number	Average stay time in seconds per participant
timestamps.startedAt	string | null	When the class started (ISO date)
timestamps.endedAt	string | null	When the class ended (ISO date), null if live
status	string	Room status: "live" or "finished"

Room Not Found (404)

If the room doesn't exist:

{
  "success": false,
  "message": "Room not found"
}

Understanding the Metrics

Total Credits

Credits are calculated based on participant session time:

• 1 credit = 1 minute of participant time
• Each participant's session durations are summed
• All participant times are totaled and rounded up

For example, if 10 participants each stayed for 30 minutes:

• Total time: 10 × 30 = 300 minutes
• Total credits: 300

Average Stay

The average stay is calculated as:

1. Sum all session durations for each participant
2. Add up all participants' total times
3. Divide by the number of unique participants

This gives you the average total time spent per participant in seconds.

To convert to minutes: avgStay / 60

Examples

JavaScript: Analytics Dashboard

async function getRoomAnalytics(roomId) {
  const response = await fetch(
    `https://api.verriflo.com/v1/room/${roomId}/summary`,
    {
      headers: { "VF-ORG-ID": process.env.VERRIFLO_ORG_ID },
    },
  );

  const { success, data } = await response.json();

  if (!success) {
    return null;
  }

  return {
    title: data.roomName,
    participants: data.totalParticipants,
    creditsUsed: data.totalCredits,
    avgStayMinutes: Math.round(data.avgStay / 60),
    status: data.status,
    duration:
      data.timestamps.endedAt && data.timestamps.startedAt
        ? Math.round(
            (new Date(data.timestamps.endedAt) -
              new Date(data.timestamps.startedAt)) /
              60000,
          )
        : null,
  };
}

Python: Generate Report

import requests
import os
from datetime import datetime

def generate_room_report(room_id: str) -> dict:
    """Generate a summary report for a room."""
    response = requests.get(
        f'https://api.verriflo.com/v1/room/{room_id}/summary',
        headers={'VF-ORG-ID': os.environ['VERRIFLO_ORG_ID']}
    )

    data = response.json()['data']

    return {
        'room_name': data['roomName'],
        'status': data['status'],
        'total_participants': data['totalParticipants'],
        'total_credits': data['totalCredits'],
        'avg_stay_minutes': round(data['avgStay'] / 60, 1),
        'started_at': data['timestamps']['startedAt'],
        'ended_at': data['timestamps']['endedAt'],
    }

PHP: Cost Calculation

function calculateRoomCost($roomId, $creditRate = 0.01) {
    $response = file_get_contents(
        "https://api.verriflo.com/v1/room/{$roomId}/summary",
        false,
        stream_context_create([
            'http' => [
                'header' => "VF-ORG-ID: " . getenv('VERRIFLO_ORG_ID')
            ]
        ])
    );

    $data = json_decode($response, true)['data'];

    return [
        'room' => $data['roomName'],
        'credits' => $data['totalCredits'],
        'cost' => $data['totalCredits'] * $creditRate,
        'participants' => $data['totalParticipants']
    ];
}

Errors

Status	Message	Description
400	Missing roomId	roomId parameter is missing
401	Unauthorized	Invalid organization ID
404	Room not found	Room doesn't exist

---

Tip: Use this endpoint after a class ends to generate session reports for teachers and administrators. Combine with the Participant Sessions endpoint for detailed per-participant breakdowns.