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 session authentication. Agent and deployment counts are sourced from the database. Performance data (averageResponseTime, successRate, errorRate, cpu, memory) is fetched from the backend metrics service when at least one active agent exists; otherwise these fields fall back to computed defaults or 0. The messages fields are not tracked in the frontend database and always return 0.

​
Response

{
  "metrics": {
    "agents": {
      "total": 4,
      "active": 4,
      "inactive": 0,
      "failed": 0
    },
    "messages": {
      "today": 0,
      "thisWeek": 0,
      "thisMonth": 0
    },
    "deployments": {
      "total": 4,
      "successful": 4,
      "failed": 0
    },
    "uptime": {
      "platformUptime": 99.9,
      "averageAgentUptime": 98.5
    },
    "performance": {
      "averageResponseTime": 450,
      "successRate": 99.1,
      "errorRate": 0,
      "cpu": 15.3,
      "memory": 42.1
    },
    "storage": {
      "used": 0,
      "total": 1024,
      "percentUsed": 0
    }
  },
  "timestamp": "2026-03-27T12:00:00Z",
  "status": "ok",
  "plan": "solo"
}

​
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. Not currently tracked; always returns 0.
metrics.messages.thisWeeknumberMessages processed this week. Not currently tracked; always returns 0.
metrics.messages.thisMonthnumberMessages processed this month. Not currently tracked; always returns 0.
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. Returns 0 when no backend data is available.
metrics.performance.successRatenumberSuccess rate percentage. Defaults to 99.1 when active agents exist but no backend data is available, or 0 when no active agents exist.
metrics.performance.errorRatenumberError rate percentage. Calculated from the ratio of failed agents when no backend data is available.
metrics.performance.cpunumberCurrent CPU usage percentage (0–100). Returns 0 when no backend data is available.
metrics.performance.memorynumberCurrent memory usage percentage (0–100). Returns 0 when no backend data is available.
metrics.storage.usednumberStorage used in MB. Currently always returns 0.
metrics.storage.totalnumberTotal storage in MB
metrics.storage.percentUsednumberStorage usage percentage. Currently always returns 0.
planstring | nullUser’s current subscription plan (for example solo, collective, label, network), or null if not set.

​
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