Usage Data

The /api/usage endpoint returns real-time usage data that changes frequently, such as CPU load, memory usage, and temperatures.

Prefer Real-Time APIs

For real-time data, we recommend using WebSocket or SSE Stream instead of polling this endpoint. Both push updates to you automatically and are more efficient.

Endpoints

Get Usage Data

Returns real-time usage data that changes frequently, such as CPU load, memory usage, and temperatures.

GET /api/usage

Response:

{
  "uptime": 86400,
  "cpu": {
    "current_load": 12.5,
    "current_speed": 5.2
  },
  "memory": {
    "used": 12456789012,
    "free": 21811522540,
    "used_percent": 36.35
  }
  // ... gpu, disks
}

Field Reference

Root Object

Field	Type	Description
`uptime`	int	System uptime in seconds.
`cpu`	object	Current CPU usage metrics.
`memory`	object	Current memory usage.
`gpu`	object	Current GPU usage (null if not detected).
`disks`	array	Current disk usage for each drive.

CPU Object

Field	Type	Description
`current_load`	float	Current CPU usage percentage.
`current_speed`	float	Current clock speed in GHz.

Memory Object

Field	Type	Description
`used`	int	Used RAM in bytes.
`free`	int	Free RAM in bytes.
`used_percent`	float	Usage as a percentage.

GPU Object

Field	Type	Description
`current_load`	int	GPU usage percentage.
`current_temp`	int	GPU temperature in °C.
`current_memory`	int	VRAM usage in MB.

Disk Object

Field	Type	Description
`fs`	string	Filesystem identifier.
`used`	int	Used space in bytes.
`available`	int	Available space in bytes.
`used_percent`	float	Usage as a percentage.

Polling Recommendation

For dashboards, poll this endpoint every 2-5 seconds. More frequent polling provides smoother updates but increases network traffic.

Example Usage Scenarios

1. Minimalistic Stat Bar

Build a tiny status bar for your second monitor.

Poll /api/usage every 5 seconds.
Display simple bars for cpu.current_load and memory.used_percent.

2. High Load Alert

Notify yourself if the server is struggling.

Monitor /api/usage.
If cpu.current_load > 90% for 1 minute:
Send a push notification to your phone.

On this page