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

Field	Type	Description
`cpu`	number	CPU usage percentage (0–100), derived from the system load average divided by the number of CPU cores
`memory`	number	Memory usage percentage (0–100)
`uptime`	number	Seconds since the web application process started
`messages`	number	In-process message counter. Resets on restart.
`errors`	number	In-process error counter. Resets on restart.
`health`	string	Overall health classification: `healthy`, `degraded`, or `unhealthy`
`timestamp`	string	ISO 8601 timestamp of the stats snapshot
`deployment.provider`	string	Hosting provider: `vercel` when running on Vercel, `node` otherwise
`deployment.environment`	string	Deployment environment (for example `production`, `preview`, `development`). Falls back to `NODE_ENV` or `unknown`.
`deployment.region`	string \| null	Deployment region identifier, or `null` when not available
`deployment.deploymentUrl`	string \| null	Public deployment URL, or `null` when not running on Vercel
`deployment.commitSha`	string \| null	Git commit SHA of the deployed build, or `null` when not available
`deployment.commitRef`	string \| null	Git branch or tag of the deployed build, or `null` when not available
`deployment.commitMessage`	string \| null	Git commit message of the deployed build, or `null` when not available
`deployment.deploymentId`	string \| null	Vercel deployment identifier, or `null` when not running on Vercel
`deployment.target`	string \| null	Vercel target environment (for example `production`, `preview`), or `null` when not running on Vercel
`deployment.projectProductionUrl`	string \| null	Production URL configured for the Vercel project, or `null` when not running on Vercel
`runtime.node`	string	Node.js version
`runtime.platform`	string	Operating system platform (for example `linux`, `darwin`)
`runtime.arch`	string	CPU architecture (for example `x64`, `arm64`)
`runtime.heapUsedMb`	number	V8 heap memory in use, in megabytes
`runtime.heapTotalMb`	number	Total V8 heap size, in megabytes
`runtime.rssMb`	number	Resident set size of the process, in megabytes
`runtime.externalMb`	number	Memory used by C++ objects bound to JavaScript objects, in megabytes

The health field is computed from CPU and memory thresholds:

Value	Condition
`healthy`	CPU ≤ 70% and memory ≤ 70% and errors ≤ 5
`degraded`	CPU > 70% or memory > 70% or errors > 5 (but below the unhealthy threshold)
`unhealthy`	CPU > 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

Code	Description
401	Unauthorized — no valid session
500	Failed 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

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
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
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.

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

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

Getting Started

Core Concepts

Integrations

Core Services

Payments

API Reference

MCP

Security

Metrics API

Metrics API

System stats

Response

Response fields

Error response

Errors

Platform metrics

Response

Response fields

Errors

Historical metrics

Path parameters

Query parameters

Response

Response fields

Errors

Performance metrics

Path parameters

Response

Response fields

Errors

Metrics summary

Path parameters

Response

Response fields

Errors

​Metrics API

​System stats

​Response

​Response fields

​Error response

​Errors

​Platform metrics

​Response

​Response fields

​Errors

​Historical metrics

​Path parameters

​Query parameters

​Response

​Response fields

​Errors

​Performance metrics

​Path parameters

​Response

​Response fields

​Errors

​Metrics summary

​Path parameters

​Response

​Response fields

​Errors

Metrics API

System stats

Response

Response fields

Error response

Errors

Platform metrics

Response

Response fields

Errors

Historical metrics

Path parameters

Query parameters

Response

Response fields

Errors

Performance metrics

Path parameters

Response

Response fields

Errors

Metrics summary

Path parameters

Response

Response fields

Errors