Skip to main content

​
Endpoints

​
Global Metrics

GET /api/v1/metrics/live
Retrieve aggregated metrics across all tenants.

​
Tenant-Specific Metrics

GET /api/v1/metrics/live/{tenant_id}
Retrieve metrics for a specific tenant.

​
Capacity Debug Metrics

GET /api/v1/metrics/capacity/debug
Get detailed capacity state for debugging capacity issues. Returns active, accepted, and pending call states.

​
Authentication

These endpoints require admin authentication using the require_admin security dependency.
​
X-Admin-Token
string
required
Admin authentication token configured in your environment settings

​
Path Parameters

​
tenant_id
string
Unique identifier for the tenant (only for tenant-specific endpoint)

​
Response

Returns a JSON object with real-time metrics tracked by the LiveMetricsStore.
​
active_calls
integer
Number of calls currently active (started but not yet ended)
​
accepted_calls
integer
Total number of calls accepted since server start
​
rejected_calls_capacity
integer
Number of calls rejected due to insufficient capacity (max concurrent calls reached)
​
rejected_calls_tenant_not_configured
integer
Number of calls rejected because the tenant is not configured in the system
​
rejected_calls_instructions_missing
integer
Number of calls rejected because instructions could not be found for the tenant
​
instructions_db_errors
integer
Number of database errors encountered while fetching instructions
​
fallback_instructions_used
integer
Number of times fallback instructions were used instead of tenant-specific instructions
​
started_calls
integer
Total number of calls that have started processing
​
ended_calls
integer
Total number of calls that have ended (completed, hung up, or errored)
​
failed_calls
integer
Number of calls that ended with an error
​
referred_calls
integer
Number of calls that were referred (transferred) to another destination
​
minutes_processed
number
Total minutes of call audio processed by the system

​
Example Request

​
Global Metrics

curl -X GET https://your-domain.com/api/v1/metrics/live \
  -H "X-Admin-Token: your-admin-token"

​
Tenant Metrics

curl -X GET https://your-domain.com/api/v1/metrics/live/tenant_123 \
  -H "X-Admin-Token: your-admin-token"

​
Example Response

​
Metrics Response

{
  "active_calls": 3,
  "accepted_calls": 150,
  "rejected_calls_capacity": 12,
  "rejected_calls_tenant_not_configured": 5,
  "rejected_calls_instructions_missing": 2,
  "instructions_db_errors": 1,
  "fallback_instructions_used": 8,
  "started_calls": 145,
  "ended_calls": 142,
  "failed_calls": 3,
  "referred_calls": 7,
  "minutes_processed": 1247.5
}

​
Capacity Debug Response

{
  "active_count": 5,
  "active_calls": [
    {"call_id": "call_abc123", "status": "RUNNING"},
    {"call_id": "call_def456", "status": "RUNNING"}
  ],
  "accepted_count": 8,
  "accepted_call_ids": ["call_abc123", "call_def456"],
  "pending_count": 2,
  "pending_call_ids": ["call_ghi789", "call_jkl012"],
  "pending_by_tenant_count": {
    "tenant_1": 1,
    "tenant_2": 1
  },
  "pending_by_tenant": {
    "tenant_1": ["call_ghi789"],
    "tenant_2": ["call_jkl012"]
  },
  "pending_tenant_by_call_id_count": 2,
  "pending_tenant_by_call_id": {
    "call_ghi789": "tenant_1",
    "call_jkl012": "tenant_2"
  }
}

​
Metrics Interpretation

​
Call Flow Metrics

  • Accepted → Started → Ended: Normal call flow progression
  • High rejected_calls_capacity: Consider increasing max_concurrent_calls setting
  • High rejected_calls_tenant_not_configured: Tenants attempting calls without proper setup
  • High rejected_calls_instructions_missing: Instructions not properly configured in database

​
Quality Metrics

  • failed_calls / ended_calls: Error rate percentage
  • fallback_instructions_used: How often the system falls back to default instructions
  • instructions_db_errors: Database connectivity or query issues

​
Capacity Metrics

  • active_calls: Current load on the system
  • minutes_processed: Total processing volume

​
Use Cases

  • Real-time Monitoring: Track system performance and call processing status
  • Capacity Planning: Analyze rejection rates to determine if capacity needs adjustment
  • Tenant Health: Monitor per-tenant metrics to identify configuration issues
  • SLA Tracking: Calculate success rates and error rates for service level agreements
  • Billing: Use minutes_processed for usage-based billing

Build docs developers (and LLMs) love

Get started for freeTalk to us