Appearance
Endpoint: Performance Monitoring
Real-time system health metrics across application, database, AI providers, and gateway layers. Use this endpoint to build dashboards, trigger operational alerts, and diagnose performance bottlenecks.
Authentication
Requires session-based authentication with the SUPER_ADMIN role. All other roles receive 403 Super Admin required.
GET /api/admin/performance-meter
Collect aggregated health metrics from all system components in a single request. Each metric is represented as a MeterZone object with a status indicator, current value, and actionable recommendation when thresholds are breached.
Example Request
bash
curl https://app.veriprompt.tech/api/admin/performance-meter \
-H "Authorization: Bearer YOUR_API_KEY"Success Response
json
{
"success": true,
"timestamp": "2026-03-24T10:15:00.000Z",
"overallStatus": "warning",
"summary": {
"total": 9,
"healthy": 7,
"warning": 1,
"critical": 0,
"unknown": 1
},
"meters": [
{
"id": "app-memory",
"label": "App Memory (Heap)",
"category": "application",
"status": "healthy",
"value": 62,
"unit": "%",
"details": "145MB / 234MB heap — RSS 312MB",
"action": null,
"thresholds": { "warning": 75, "critical": 90 }
},
{
"id": "app-uptime",
"label": "Uptime",
"category": "application",
"status": "healthy",
"value": 72.3,
"unit": "hours",
"details": "Process running for 72.3h",
"action": null
},
{
"id": "db-latency",
"label": "Database Latency",
"category": "database",
"status": "healthy",
"value": 12,
"unit": "ms",
"details": "Simple query: 12ms",
"action": null,
"thresholds": { "warning": 100, "critical": 500 }
},
{
"id": "db-cache",
"label": "DB Cache Hit Ratio",
"category": "database",
"status": "healthy",
"value": 99.12,
"unit": "%",
"details": "99.12% of queries served from cache",
"action": null,
"thresholds": { "warning": 95, "critical": 90 }
},
{
"id": "db-connections",
"label": "Active DB Connections",
"category": "database",
"status": "healthy",
"value": 8,
"unit": "connections",
"details": "8 active connections to database",
"action": null,
"thresholds": { "warning": 40, "critical": 80 }
},
{
"id": "db-size",
"label": "Database Size",
"category": "database",
"status": "healthy",
"value": 256,
"unit": "MB",
"details": "Total database size: 256MB",
"action": null,
"thresholds": { "warning": 4000, "critical": 8000 }
},
{
"id": "provider-trust",
"label": "Avg Provider Trust Score",
"category": "providers",
"status": "warning",
"value": 68,
"unit": "/100",
"details": "3 active provider(s) — average trust score 68/100",
"action": "Provider quality degraded — check individual provider health and consider routing adjustments.",
"thresholds": { "warning": 70, "critical": 50 }
},
{
"id": "provider-count",
"label": "Active Providers",
"category": "providers",
"status": "healthy",
"value": 3,
"unit": "providers",
"details": "3 AI provider(s) configured and active",
"action": null
},
{
"id": "gw-executions-24h",
"label": "Gateway Executions (24h)",
"category": "gateway",
"status": "healthy",
"value": 1847,
"unit": "requests",
"details": "1847 requests in last 24h — 42310 total all-time",
"action": null
}
],
"actionItems": [
{
"meterId": "provider-trust",
"category": "providers",
"label": "Avg Provider Trust Score",
"severity": "warning",
"action": "Provider quality degraded — check individual provider health and consider routing adjustments."
}
]
}MeterZone Object
Each item in the meters array follows this structure:
| Field | Type | Description |
|---|---|---|
id | string | Unique meter identifier (e.g., app-memory, db-latency) |
label | string | Human-readable meter name |
category | string | One of: application, database, providers, gateway |
status | string | Current health: healthy, warning, critical, or unknown |
value | number | string | Current metric value. String "N/A" when the metric cannot be collected. |
unit | string | Unit of measurement (e.g., %, ms, connections, providers, requests) |
details | string | Human-readable description of the current state |
action | string | null | Recommended remediation when status is warning or critical. Null when healthy. |
thresholds | object | undefined | Optional { warning: number, critical: number } defining the boundary values |
Metric Categories
Application
| Meter | What It Measures | Thresholds |
|---|---|---|
app-memory | V8 heap usage as a percentage of total heap | Warning: >75%, Critical: >90% |
app-uptime | Process uptime in hours | Warning: <0.1h (possible crash loop) |
Database
| Meter | What It Measures | Thresholds |
|---|---|---|
db-latency | Round-trip time for a SELECT 1 query | Warning: >100ms, Critical: >500ms |
db-cache | PostgreSQL buffer cache hit ratio | Warning: <95%, Critical: <90% |
db-connections | Active connections to the database | Warning: >40, Critical: >80 |
db-size | Total database size in MB or GB | Warning: >4GB, Critical: >8GB |
When the database is unreachable, db-latency reports value: "N/A" with status critical.
Providers
| Meter | What It Measures | Thresholds |
|---|---|---|
provider-trust | Average trust score across all active providers | Warning: <70, Critical: <50 |
provider-unhealthy | Count of providers with trust score below 50 | Always critical when present |
provider-count | Number of active AI providers | Warning: <2 (no fallback), Critical: 0 |
Provider trust scores are derived from the most recent ProviderHealthSnapshot within the last 24 hours. Each provider's health snapshot tracks success rates, latency patterns, and error frequency.
Gateway
| Meter | What It Measures | Thresholds |
|---|---|---|
gw-executions-24h | Prompt executions through the gateway in the last 24 hours | Informational (always healthy) |
Circuit Breaker States
Provider health monitoring uses a circuit breaker pattern to protect the system from cascading failures:
| State | Description | Behavior |
|---|---|---|
closed | Normal operation | All requests routed normally to the provider |
open | Provider disabled | No requests sent. Triggered when error rate exceeds 50%. Automatic 5-minute cooldown before re-testing. |
half-open | Testing recovery | A limited number of requests are sent to check if the provider has recovered. On success, returns to closed. On failure, returns to open. |
When a provider's circuit breaker opens, the routing engine automatically redirects traffic to healthy providers. The provider-unhealthy meter tracks providers currently in open or degraded state.
Overall Status
The overallStatus field in the response is computed from all meters:
| Value | Condition |
|---|---|
critical | One or more meters report critical |
warning | No critical meters, but one or more report warning |
healthy | All meters report healthy (or unknown) |
Action Items
The actionItems array provides a filtered list of meters that require attention, each with a concrete remediation step. Use this array to power alerting integrations or dashboard notifications without parsing the full meters array.
json
{
"meterId": "db-latency",
"category": "database",
"label": "Database Latency",
"severity": "critical",
"action": "Latency >500ms — upgrade DB tier or check managed DB dashboard for IOPS saturation."
}Error Responses
| Status | Body | Cause |
|---|---|---|
401 | { "error": "Unauthorized" } | No active session |
403 | { "error": "Super Admin required" } | User is not a Super Admin |
500 | { "error": "Failed to collect performance metrics" } | Internal server error |