Get Status History

Learn how to retrieve the complete history of status changes for a meeting, showing when and why the bot transitioned between states.

Overview

Status history is included in the meeting data when you fetch a meeting via the REST API. It shows all status transitions with timestamps, sources, and reasons.

Status History Structure

Each status transition includes:

from - Previous status
to - New status
timestamp - When the transition occurred (ISO 8601)
source - What triggered the change (e.g., "bot_callback", "user_api")
reason - Optional reason for the transition
completion_reason - Reason for completion (if status is "completed")

Where to Find It

Status history is available in the data.status_transition field when you fetch a meeting via:

GET /meetings - List all meetings
GET /transcripts/{platform}/{native_meeting_id} - Get meeting with transcripts

Implementation

Fetch a meeting and access its status history

JavaScript/TypeScript Example

// Get meeting with status history
async function getMeetingWithStatusHistory(platform, nativeMeetingId) {
  // Option 1: Get via transcripts endpoint (includes full meeting data)
  const response = await fetch(
    `https://your-api-url/transcripts/${platform}/${nativeMeetingId}`,
    {
      headers: {
        'X-API-Key': 'your-api-key',
        'Content-Type': 'application/json'
      }
    }
  );
  
  if (!response.ok) {
    throw new Error(`Failed to fetch meeting: ${response.statusText}`);
  }
  
  const data = await response.json();
  
  // Status history is in data.data.status_transition
  const statusHistory = data.data?.status_transition || [];
  
  console.log(`Found ${statusHistory.length} status transitions`);
  
  // Display status history
  statusHistory.forEach((transition, index) => {
    console.log(`${index + 1}. ${transition.from} → ${transition.to}`);
    console.log(`   Time: ${transition.timestamp}`);
    console.log(`   Source: ${transition.source || 'unknown'}`);
    if (transition.reason) {
      console.log(`   Reason: ${transition.reason}`);
    }
  });
  
  return statusHistory;
}

// Usage
const history = await getMeetingWithStatusHistory('google_meet', 'abc-defg-hij');

// Or get from meetings list
async function getAllMeetingsWithHistory() {
  const response = await fetch('https://your-api-url/meetings', {
    headers: {
      'X-API-Key': 'your-api-key',
      'Content-Type': 'application/json'
    }
  });
  
  const data = await response.json();
  
  // Each meeting in data.meetings has status_transition
  data.meetings.forEach(meeting => {
    const history = meeting.data?.status_transition || [];
    console.log(`Meeting ${meeting.native_meeting_id} has ${history.length} status transitions`);
  });
  
  return data.meetings;
}

Status Transition Example

Example status history showing a typical bot lifecycle

[
  {
    "from": null,
    "to": "requested",
    "timestamp": "2024-01-01T12:00:00Z",
    "source": "user_api",
    "reason": null
  },
  {
    "from": "requested",
    "to": "joining",
    "timestamp": "2024-01-01T12:00:15Z",
    "source": "bot_callback",
    "reason": null
  },
  {
    "from": "joining",
    "to": "awaiting_admission",
    "timestamp": "2024-01-01T12:00:30Z",
    "source": "bot_callback",
    "reason": null
  },
  {
    "from": "awaiting_admission",
    "to": "active",
    "timestamp": "2024-01-01T12:01:00Z",
    "source": "bot_callback",
    "reason": null
  },
  {
    "from": "active",
    "to": "completed",
    "timestamp": "2024-01-01T13:00:00Z",
    "source": "bot_callback",
    "completion_reason": "meeting_ended"
  }
]

This shows a complete bot lifecycle:

Bot created via user API (requested)
Bot container started and connecting (joining)
Bot in waiting room (awaiting_admission)
Bot admitted and transcribing (active)
Meeting ended (completed)

Use Cases

•Debugging: Understand why a bot got stuck or failed by examining the status transitions and their timestamps.
•Analytics: Track how long bots spend in each state to identify bottlenecks (e.g., long waiting room times).
•UI Display: Show a timeline of status changes to users, similar to the dashboard's Status History component.
•Monitoring: Alert when bots stay in certain states too long (e.g., awaiting_admission for more than 5 minutes).