Metrics API

Endpoints for retrieving agent performance metrics and music industry analytics

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

Field	Type	Description
metrics.agents.total	number	Total number of agents
metrics.agents.active	number	Currently running agents
metrics.agents.inactive	number	Stopped agents
metrics.agents.failed	number	Agents in a failed state
metrics.messages.today	number	Messages processed today. Not currently tracked; always returns 0.
metrics.messages.thisWeek	number	Messages processed this week. Not currently tracked; always returns 0.
metrics.messages.thisMonth	number	Messages processed this month. Not currently tracked; always returns 0.
metrics.deployments.total	number	Total deployments
metrics.deployments.successful	number	Successful deployments
metrics.deployments.failed	number	Failed deployments
metrics.uptime.platformUptime	number	Platform uptime percentage
metrics.uptime.averageAgentUptime	number	Average agent uptime percentage
metrics.performance.averageResponseTime	number	Average response time in milliseconds. Returns 0 when no backend data is available.
metrics.performance.successRate	number	Success 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.errorRate	number	Error rate percentage. Calculated from the ratio of failed agents when no backend data is available.
metrics.performance.cpu	number	Current CPU usage percentage (0–100). Returns 0 when no backend data is available.
metrics.performance.memory	number	Current memory usage percentage (0–100). Returns 0 when no backend data is available.
metrics.storage.used	number	Storage used in MB. Currently always returns 0.
metrics.storage.total	number	Total storage in MB
metrics.storage.percentUsed	number	Storage usage percentage. Currently always returns 0.
plan	string | null	User’s current subscription plan (for example solo, collective, label, network), or null if not set.

Errors

Code	Description
401	Unauthorized — missing or invalid bearer token
500	Failed 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

Parameter	Type	Description
userId	string	ID of the user whose agent metrics to retrieve

Query parameters

Parameter	Type	Default	Description
range	string	24h	Time 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

Field	Type	Description
userId	string	User ID for the metrics
timeRange	string	Requested time range
metrics	array	Array of metric data points
metrics[].timestamp	string	ISO 8601 timestamp for the data point
metrics[].cpu	number	CPU usage percentage (0–100)
metrics[].memory	number	Memory usage percentage (0–100)
metrics[].messages	number	Messages processed in the period
metrics[].errors	number	Errors in the period
averages.cpu	number	Average CPU usage over the time range
averages.memory	number	Average memory usage over the time range
averages.messages	number	Average messages per period
averages.errors	number	Average errors per period

Errors

Code	Description
401	Unauthorized — missing or invalid bearer token
403	Forbidden — invalid API key
500	Failed 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

Parameter	Type	Description
userId	string	ID of the user whose agent performance to retrieve

Response

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

Response fields

Field	Type	Description
cpu	number	Current CPU usage percentage (0–100)
memory	number	Current memory usage percentage (0–100)
errorRate	number	Error rate percentage calculated from agent logs
responseTime	number	Response time in milliseconds. Currently always returns 0 — real instrumentation is not yet implemented.

Errors

Code	Description
401	Unauthorized — missing or invalid bearer token
403	Forbidden — invalid API key
500	Failed 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

Parameter	Type	Description
userId	string	ID 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

Field	Type	Description
revenue.month	string	Revenue for the current month
revenue.total	string	Total lifetime revenue
revenue.change	string	Month-over-month revenue change
bookings.completed	number	Number of completed bookings
bookings.pending	number	Number of pending bookings
bookings.conversion	string	Booking conversion rate
fans.total	number	Total fan count
fans.active	number	Active fans
fans.growth	string	Fan growth rate
fans.segmentation.superfans	number	Number of superfans
fans.segmentation.casual	number	Number of casual fans
fans.segmentation.new	number	Number of new fans
streams.monthlyListeners	number	Monthly listener count
streams.monthlyStreams	number	Monthly stream count
streams.growth	string	Streaming growth rate
skills.active	number	Number of active skills
skills.total	number	Total skills available
skills.growth	string	Skills adoption growth rate

Errors

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