Skip to main content

​
Metrics API

Retrieve agent performance data, historical metrics, and music industry analytics.

​
Base URL

https://agentbot.raveculture.xyz/api/metrics

​
Platform metrics

GET /api/metrics
This endpoint is served by the web application, not the backend API service. It is not available on the backend base URL.
Returns platform-wide metrics including agent counts, message volumes, deployment stats, uptime, performance, and storage usage. Requires bearer token (API key) authentication.
The messages, performance, and storage.used fields currently return randomized mock data. Agent and deployment counts are retrieved from the database. A future release will connect all fields to real telemetry.

​
Response

{
  "metrics": {
    "agents": {
      "total": 4,
      "active": 4,
      "inactive": 0,
      "failed": 0
    },
    "messages": {
      "today": 12500,
      "thisWeek": 87000,
      "thisMonth": 350000
    },
    "deployments": {
      "total": 4,
      "successful": 4,
      "failed": 0
    },
    "uptime": {
      "platformUptime": 99.9,
      "averageAgentUptime": 98.5
    },
    "performance": {
      "averageResponseTime": 450,
      "successRate": "98.50",
      "errorRate": "1.50"
    },
    "storage": {
      "used": 180,
      "total": 1024,
      "percentUsed": 35
    }
  },
  "timestamp": "2026-03-19T12:00:00Z",
  "status": "ok"
}

​
Response fields

FieldTypeDescription
metrics.agents.totalnumberTotal number of agents
metrics.agents.activenumberCurrently running agents
metrics.agents.inactivenumberStopped agents
metrics.agents.failednumberAgents in a failed state
metrics.messages.todaynumberMessages processed today
metrics.messages.thisWeeknumberMessages processed this week
metrics.messages.thisMonthnumberMessages processed this month
metrics.deployments.totalnumberTotal deployments
metrics.deployments.successfulnumberSuccessful deployments
metrics.deployments.failednumberFailed deployments
metrics.uptime.platformUptimenumberPlatform uptime percentage
metrics.uptime.averageAgentUptimenumberAverage agent uptime percentage
metrics.performance.averageResponseTimenumberAverage response time in milliseconds
metrics.performance.successRatestringSuccess rate percentage
metrics.performance.errorRatestringError rate percentage
metrics.storage.usednumberStorage used in MB
metrics.storage.totalnumberTotal storage in MB
metrics.storage.percentUsednumberStorage usage percentage

​
Errors

CodeDescription
401Unauthorized — missing or invalid bearer token
500Failed to fetch metrics. The error response includes an empty metrics object alongside the error field: { "error": "Failed to fetch metrics", "metrics": {} }

​
Historical metrics

The per-user metrics endpoints below are served by the backend API service, not the web application. They are available at the backend base URL, which may differ from the web API base URL depending on your deployment.
GET /api/metrics/:userId/historical
Requires bearer token authentication. Returns time-series metrics for an agent over a specified time range. Data is sourced from the container_metrics database table, aggregated by hour. If no database history exists for the requested range, the endpoint falls back to a single live container sample.

​
Path parameters

ParameterTypeDescription
userIdstringID of the user whose agent metrics to retrieve

​
Query parameters

ParameterTypeDefaultDescription
rangestring24hTime range for metrics. Options: 24h, 7d, 30d

​
Response

{
  "userId": "user_123",
  "timeRange": "24h",
  "metrics": [
    {
      "timestamp": "2026-03-18T12:00:00Z",
      "cpu": 15.3,
      "memory": 42.1,
      "messages": 85,
      "errors": 2
    }
  ],
  "averages": {
    "cpu": 18,
    "memory": 45,
    "messages": 72,
    "errors": 3
  }
}

​
Response fields

FieldTypeDescription
userIdstringUser ID for the metrics
timeRangestringRequested time range
metricsarrayArray of metric data points
metrics[].timestampstringISO 8601 timestamp for the data point
metrics[].cpunumberCPU usage percentage (0–100)
metrics[].memorynumberMemory usage percentage (0–100)
metrics[].messagesnumberMessages processed in the period
metrics[].errorsnumberErrors in the period
averages.cpunumberAverage CPU usage over the time range
averages.memorynumberAverage memory usage over the time range
averages.messagesnumberAverage messages per period
averages.errorsnumberAverage errors per period

​
Errors

CodeDescription
401Unauthorized — missing or invalid bearer token
403Forbidden — invalid API key
500Failed to fetch historical metrics

​
Performance metrics

GET /api/metrics/:userId/performance
Requires bearer token authentication. Returns current real-time performance data for an agent.

​
Path parameters

ParameterTypeDescription
userIdstringID of the user whose agent performance to retrieve

​
Response

{
  "cpu": 15.3,
  "memory": 42.1,
  "errorRate": 1.2,
  "responseTime": 0
}

​
Response fields

FieldTypeDescription
cpunumberCurrent CPU usage percentage (0–100)
memorynumberCurrent memory usage percentage (0–100)
errorRatenumberError rate percentage calculated from agent logs
responseTimenumberResponse time in milliseconds. Currently always returns 0 — real instrumentation is not yet implemented.

​
Errors

CodeDescription
401Unauthorized — missing or invalid bearer token
403Forbidden — invalid API key
500Failed to fetch performance data

​
Metrics summary

GET /api/metrics/:userId/summary
Requires bearer token authentication. Returns a music industry analytics summary for an agent, including revenue, bookings, fan engagement, streaming stats, and active skills.

​
Path parameters

ParameterTypeDescription
userIdstringID of the user whose metrics summary to retrieve

​
Response

{
  "revenue": {
    "month": "$0.00",
    "total": "$0.00",
    "change": "+0%"
  },
  "bookings": {
    "completed": 0,
    "pending": 0,
    "conversion": "0%"
  },
  "fans": {
    "total": 0,
    "active": 0,
    "growth": "+0%",
    "segmentation": {
      "superfans": 0,
      "casual": 0,
      "new": 0
    }
  },
  "streams": {
    "monthlyListeners": 0,
    "monthlyStreams": 0,
    "growth": "+0%"
  },
  "skills": {
    "active": 0,
    "total": 0,
    "growth": "+0%"
  }
}

​
Response fields

FieldTypeDescription
revenue.monthstringRevenue for the current month
revenue.totalstringTotal lifetime revenue
revenue.changestringMonth-over-month revenue change
bookings.completednumberNumber of completed bookings
bookings.pendingnumberNumber of pending bookings
bookings.conversionstringBooking conversion rate
fans.totalnumberTotal fan count
fans.activenumberActive fans
fans.growthstringFan growth rate
fans.segmentation.superfansnumberNumber of superfans
fans.segmentation.casualnumberNumber of casual fans
fans.segmentation.newnumberNumber of new fans
streams.monthlyListenersnumberMonthly listener count
streams.monthlyStreamsnumberMonthly stream count
streams.growthstringStreaming growth rate
skills.activenumberNumber of active skills
skills.totalnumberTotal skills available
skills.growthstringSkills adoption growth rate

​
Errors

CodeDescription
401Unauthorized — missing or invalid bearer token
403Forbidden — invalid API key
500Failed to fetch metrics summary