Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.agentbot.raveculture.xyz/llms.txt

Use this file to discover all available pages before exploring further.

​
Metrics API

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

​
System stats

GET /api/stats
Requires session authentication. Returns server-level resource usage, in-process counters, health classification, and deployment metadata.
The in-process counters (messages and errors) are held in memory and reset when the web application restarts. They are not persisted to a database.

​
Response

{
  "cpu": 12.5,
  "memory": 67.3,
  "uptime": 3600,
  "messages": 0,
  "errors": 0,
  "health": "healthy",
  "timestamp": "2026-04-03T12:00:00.000Z",
  "deployment": {
    "provider": "vercel",
    "environment": "production",
    "region": "iad1",
    "deploymentUrl": "https://agentbot.vercel.app",
    "commitSha": "abc123def456",
    "commitRef": "main",
    "commitMessage": "Improve dashboard stats",
    "deploymentId": "dpl_abc123",
    "target": "production",
    "projectProductionUrl": "agentbot.vercel.app"
  },
  "runtime": {
    "node": "v22.14.0",
    "platform": "linux",
    "arch": "x64",
    "heapUsedMb": 85.3,
    "heapTotalMb": 128.0,
    "rssMb": 156.2,
    "externalMb": 2.1
  }
}

​
Response fields

FieldTypeDescription
cpunumberCPU usage percentage (0–100), derived from the system load average divided by the number of CPU cores
memorynumberMemory usage percentage (0–100)
uptimenumberSeconds since the web application process started
messagesnumberIn-process message counter. Resets on restart.
errorsnumberIn-process error counter. Resets on restart.
healthstringOverall health classification: healthy, degraded, or unhealthy
timestampstringISO 8601 timestamp of the stats snapshot
deployment.providerstringHosting provider: vercel when running on Vercel, node otherwise
deployment.environmentstringDeployment environment (for example production, preview, development). Falls back to NODE_ENV or unknown.
deployment.regionstring | nullDeployment region identifier, or null when not available
deployment.deploymentUrlstring | nullPublic deployment URL, or null when not running on Vercel
deployment.commitShastring | nullGit commit SHA of the deployed build, or null when not available
deployment.commitRefstring | nullGit branch or tag of the deployed build, or null when not available
deployment.commitMessagestring | nullGit commit message of the deployed build, or null when not available
deployment.deploymentIdstring | nullVercel deployment identifier, or null when not running on Vercel
deployment.targetstring | nullVercel target environment (for example production, preview), or null when not running on Vercel
deployment.projectProductionUrlstring | nullProduction URL configured for the Vercel project, or null when not running on Vercel
runtime.nodestringNode.js version
runtime.platformstringOperating system platform (for example linux, darwin)
runtime.archstringCPU architecture (for example x64, arm64)
runtime.heapUsedMbnumberV8 heap memory in use, in megabytes
runtime.heapTotalMbnumberTotal V8 heap size, in megabytes
runtime.rssMbnumberResident set size of the process, in megabytes
runtime.externalMbnumberMemory used by C++ objects bound to JavaScript objects, in megabytes
The health field is computed from CPU and memory thresholds:
ValueCondition
healthyCPU ≤ 70% and memory ≤ 70% and errors ≤ 5
degradedCPU > 70% or memory > 70% or errors > 5 (but below the unhealthy threshold)
unhealthyCPU > 85% or memory > 85% or errors > 10

​
Error response

On failure, the endpoint returns HTTP 500 with zeroed counters and health: "unhealthy": 
{
  "cpu": 0,
  "memory": 0,
  "uptime": 0,
  "messages": 0,
  "errors": 1,
  "health": "unhealthy",
  "timestamp": "2026-04-03T12:00:00.000Z",
  "deployment": {
    "provider": "vercel",
    "environment": "production",
    "region": null,
    "deploymentUrl": null,
    "commitSha": null,
    "commitRef": null,
    "commitMessage": null,
    "deploymentId": null,
    "target": null,
    "projectProductionUrl": null
  },
  "runtime": {
    "node": "v22.14.0",
    "platform": "linux",
    "arch": "x64",
    "heapUsedMb": 0,
    "heapTotalMb": 0,
    "rssMb": 0,
    "externalMb": 0
  }
}

​
Errors

CodeDescription
401Unauthorized — no valid session
500Failed to collect system stats. Returns zeroed fallback data (see above).

​
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
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
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.
This endpoint currently returns hardcoded placeholder data. All fields return zero or $0.00 values. Real data integration is not yet implemented. The response shape is stable and will be populated with live data in a future release.

​
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
500Failed to fetch metrics summary